Ghost Kitchen & Virtual Brand Intelligence

Turn a buyer-authorized business-listing cohort into a ranked, traceable investigation queue. The Actor analyzes only supplied observations: it does not scrape delivery marketplaces, geocode, enrich with Yelp, refresh Overture, discover businesses, or transmit the cohort to another provider.

Product boundary: this is supplied-cohort decision support, not a market crawler or source-of-truth service. Results describe only the records the buyer is authorized to provide. They remain directional, traceable, and explicit about missing or conflicting evidence.

What The Actor Produces

A successful analyze_supplied run writes, in order:

1. one or more ghost-investigation-action-v1 items to the default Dataset through the no-blind-retry write policy;
2. INTELLIGENCE_REPORT using ghost-intelligence-report-v1;
3. compact OUTPUT using ghost-intelligence-output-v1; and
4. a charge-ready or budget-blocked BUNDLE_STATE using ghost-useful-bundle-state-v1;
5. at most one investigation-bundle-completed charge request, only when the complete useful bundle exists and the spending-limit setting permits it; and
6. final BUNDLE_STATE settlement authority after any charge attempt.

The Dataset is the action surface. Each row retains the action and trace ids, candidate label, priority, declared market/cohort boundary, exact source labels, supporting and contradicting observation references, evidence band, conflict and freshness state, what to inspect, why, missing evidence, what would change the assessment, and limitations.

The full report retains selected observations, duplicate receipts, resolved entities, review items, signals, actions, coverage, evidence appendix, and closed action traces. It also records Actor-derived analysis/retrieval clocks, rules/source-plan revisions, a selected-input SHA-256 digest, and a body-free storage-reference hash. It does not copy raw input bodies, unselected source columns, credentials, authorization values, or query secrets.

The output is directional investigation support. It does not label a business fraudulent, illegal, deceptive, or a confirmed ghost kitchen. A shared address does not establish ownership. A no-signal result does not establish market absence. Coverage is the declared supplied cohort, never a market census, demand estimate, share estimate, or evergreen source claim.

Inline Input

Provide 1-250 selected records and an exact production context:

{
  "mode": "analyze_supplied",
  "market": {
    "label": "Exampleville, ZZ (fictional)",
    "countryCode": "US"
  },
  "rightsBasis": "otherwise_authorized",
  "freshnessHorizonDays": 3650,
  "records": [
    {
      "name": "Fictional Brand Alpha",
      "address": "100 Fictional Foundry Way, Exampleville, ZZ 00000",
      "sourceLabel": "fictional_operator_export",
      "sourceRecordId": "alpha-001",
      "observedAt": "2026-08-01T12:00:00Z",
      "operatingObservation": "delivery_only"
    },
    {
      "name": "Fictional Brand Beta",
      "address": "100 Fictional Foundry Way, Exampleville, ZZ 00000",
      "sourceLabel": "fictional_licensed_directory",
      "sourceRecordId": "beta-001",
      "observedAt": "2026-08-02T12:00:00Z"
    }
  ]
}

mode must be analyze_supplied. rightsBasis must be exactly one of first_party, licensed_for_analysis, or otherwise_authorized. freshnessHorizonDays is 1-3,650. The Actor derives analysisId from the current run scope plus the body-free selected-input digest, and owns retrieval and analysis clocks plus rule/source-plan revisions; callers do not supply them.

Each record requires a nonblank name, address, and sourceLabel. A top-level sourceLabelDefault can supply the label only when a row omits it. Optional selected facts are sourceRecordId, RFC 3339 observedAt, business website, business phone, category, declaredBrand, and explicit operatingObservation (delivery_only or dine_in). Unknown inline fields fail closed. Buyer observedAt is nullable source evidence, cannot be in the future, and is never replaced by retrieval time. Website facts must be credential-free absolute HTTP(S) URLs without a query or fragment.

Input above 250 records fails; it is never silently truncated.

Bounded Storage Sources

Instead of records, provide one source:

• type: "file" reads a credential-free https://api.apify.com KVS record URL produced by the file-upload control;
• type: "dataset" reads a selected Dataset id/name using bounded paging and selected fields only; or
• type: "keyValueStore" reads one selected KVS id/name and record key.

File and KVS records accept CSV, JSON Lines, or one JSON array. The format can be declared as csv, jsonl, or json; otherwise content type, record-key suffix, and bounded body shape are considered in that order. Every KVS/file body is capped at 8,000,000 bytes. Dataset reads request at most 100 rows per page, at most 2,000,000 selected bytes per page, and only enough pages to distinguish 250 rows from an over-limit 251st row. Dataset metadata is not used as row-count authority.

Example Dataset source:

{
  "mode": "analyze_supplied",
  "market": { "label": "Chicago, IL", "countryCode": "US" },
  "rightsBasis": "licensed_for_analysis",
  "freshnessHorizonDays": 90,
  "sourceLabelDefault": "licensed_directory_export",
  "source": {
    "type": "dataset",
    "datasetId": "MY_DATASET_ID_OR_NAME",
    "fieldMap": {
      "name": "business_name",
      "address": "street_address",
      "sourceLabel": "source_name",
      "sourceRecordId": "source_id",
      "observedAt": "observed_at",
      "website": "website",
      "phone": "business_phone",
      "category": "category",
      "declaredBrand": "declared_brand",
      "operatingObservation": "operating_observation"
    }
  }
}

Field-map values must be ten distinct top-level source field names. Name and address must exist as nonblank strings in each selected row; the other mapped fields may be missing or null. Columns not named by the field map never enter the decision model or durable outputs. The source selector itself is retained only as a SHA-256 hash.

The schema requests READ permission for Dataset and KVS selectors. It never requests WRITE permission to the supplied source. File URLs with credentials, query parameters, non-Apify hosts, or arbitrary network locations fail before the source read.

Source And Rights Policy

buyer_supplied_v1 is the only admitted production source card. A rights declaration applies only to business-listing analysis within this product; it does not convert upload into blanket permission. Inline unknown fields and any attempt to map unsupported personal/private targeting facts fail or remain unselected before analysis.

The default executable route reaches the source-neutral intelligence core before any legacy provider construction. DoorDash, Uber Eats, Grubhub, Yelp, geocoding, Overture, the fictional demo, and old live collectors are not selectors on this route. Those modules remain in source history for separately governed recovery, but their presence does not authorize or activate them.

Multiple source labels remain separate through observations, coverage, action rows, and traces. Missing evidence is not converted to negative evidence. Sparse, stale, unknown-freshness, conflicting, collect_more_data, and no_actionable_signal results can still be useful when they close to an honest next action and the complete required bundle is durable.

Durability, Recovery, And Billing Boundary

Pricing uses Pay Per Event: one eligible completed investigation bundle costs USD 0.10, regardless of its record or action count. Review the current Store price and set your spending limit before running. The fictional prefill is a worked example; replace it with data you are authorized to analyze. Clear the inline records field when choosing a storage source, and choose a freshness horizon appropriate to your evidence.

The useful unit is exactly completed_useful_investigation_bundle_v1, at most one per accepted cohort and analysis identity. It is eligible only after:

• at least one unique supplied observation is accepted;
• the source-neutral analysis completes with an honest next action;
• the no-blind-retry Dataset action write is acknowledged;
• INTELLIGENCE_REPORT and OUTPUT are acknowledged; and
• the complete BUNDLE_STATE record is acknowledged.

An invalid schema/rights declaration, empty or over-limit cohort, source-read failure, pre-output failure, incomplete KVS/OUTPUT bundle, or unknown Dataset commit is not eligible.

Dataset writes are append-only, so any 5xx or transport ambiguity is recorded as dataset_commit_unknown. The Actor performs exactly one write attempt, does not replay it, marks the bundle ineligible, and directs the operator to a GET-first reconciliation of exact actionId values. Later KVS/OUTPUT failures similarly preserve partial acknowledgement state and GET-first guidance when BUNDLE_STATE itself can still be written.

Production billing is one deliberately narrow boundary:

• billingActivation is pay_per_event_configured;
• the only event is investigation-bundle-completed, titled Investigation bundle completed, at USD 0.10;
• one completed durable cohort bundle is one unit, regardless of record or action count, and platform usage is not passed through as another charge;
• Dataset actions, INTELLIGENCE_REPORT, compact pre-settlement OUTPUT, and a charge-ready BUNDLE_STATE are acknowledged before the charge request;
• the caller supplies one stable opaque idempotency key and persists only its SHA-256 hash;
• ACTOR_MAX_TOTAL_CHARGE_USD, when present, is parsed in integer micro-USD. A limit below USD 0.10 or any invalid setting preserves the useful output and attempts no charge;
• a successful HTTP acknowledgement settles charged; a platform limit response settles spending_limit_reached; and an unacknowledged or contradictory response settles uncertain_do_not_retry with GET-first recovery guidance; and
• re-entry into an exact charged checkpoint returns already_charged without replaying Dataset, KVS, OUTPUT, or charge effects.

Invalid input, incomplete output, unknown Dataset commit, legacy migration, and ambiguous settlement never charge. OUTPUT records the pre-settlement state and points to BUNDLE_STATE as the final authority. A charge-ready or charged local bundle is not public release, Store listing, recurrence, source-reliability, buyer-value, ROI, satisfaction, or support proof.

Retired Input Compatibility

Historical fields such as location, locations, demoMode, source scan controls, and yelpApiKey remain recognizable for saved-input compatibility. A legacy-only request writes one compact ghost-intelligence-output-v1 migration_required result with zero Dataset rows, report/state writes, provider calls, and custom charges. Even demoMode: true cannot activate the old fictional demo.

Mixing any retired key with a new supplied-intelligence key fails before a storage read, status write, durable artifact, provider construction, or charge. An empty input follows the same legacy-migration route rather than guessing a source or silently starting work.

Permissions And Disclaimer

This Actor uses limited permissions. It reads only the Apify input/storage resources you explicitly select and writes its run's output resources. Grant access only to resources you are authorized to use. It does not request broad account permissions or send your cohort to third-party data providers.

This is an unofficial, independent analysis tool. It is not affiliated with, endorsed by, or an authoritative source for any delivery marketplace, restaurant, brand or directory. The buyer remains responsible for rights to supplied data and for verifying any operating relationship before acting on a result.

Current Limitations

• This is a supplied-cohort analysis product, not automatic discovery, continuous monitoring, or an evergreen source system.
• The accepted core ranks investigation work; ranking calibration and buyer copy can improve without weakening uncertainty or traceability.
• Optional HTML is intentionally absent. JSON and Dataset outputs are the authoritative useful surfaces.
• One run accepts at most 250 records. No throughput or cost claim above that boundary is made.
• Hosted release, pricing, recurrence, monitoring, support, benchmark, and Store state are operating facts; this README does not substitute for their current platform readback.

See ./CHANGELOG.md for source-package history.