Container Delay & Free-Time Evidence Monitor

Production charging contract: container-exception-evidence-production-charging-amendment-r1. It records the pinned apify@3.7.2 production receipts and narrowly supersedes the older default-Dataset pricing-shape wording; customer-rights, source and product semantics are unchanged.

Limited-permissions production amendment: container-exception-evidence-limited-permissions-remediation-r2. Customer snapshot runs use caller-carried continuation state. They do not open a Request Queue, use a named KVS, persist durable intent, or claim cross-run idempotency. The first complete snapshot returns a baseline state; a later snapshot passes that exact state back as continuationState and receives the exact next state in nextContinuationState.

Turn an authorized customer snapshot of container events into a deterministic evidence report. The Actor compares the supplied timeline with the last healthy baseline and identifies ETA slips, missing or out-of-order milestones, gate/empty-return pairing problems, free-time exposure and customer-assumption cost exposure.

This Actor does not scrape carriers, call a provider, resolve a reference, use AIS, accept credentials, determine carrier truth, issue a legal/compliance verdict, or sell raw events. Input remains customer-owned or customer-authorized data and requires the five-field rights attestation.

Machine contract

• Input is a closed snapshot object or the exact synthetic_demo fixture.
• All calculations are deterministic and use UTC-normalized timestamps, sorted canonical JSON and domain-separated SHA-256 digests.
• Customer BOL and booking values are never returned; only domain-separated digests are exposed.
• Safe ref: and HTTPS references are validated but never fetched.
• REPORTS is the default Dataset: one immutable pre-push decisionPayload, without receipts or post-push facts.
• OUTPUT is the default KVS record: the authoritative terminal status, receipt, billing, baseline and replay facts. MCP consumers must read OUTPUT.
• The only MCP tool is container_exception_evidence.run.
• The executable MCP adapter is exported from lib/mcp.js (package export ./mcp). It returns one text item whose canonical JSON parses byte-for-value to the same structuredContent OUTPUT; it never substitutes REPORTS.

What to upload

Upload one JSON object containing watchId, mode, sourceStatus, rightsAttestation, containers, events, and tariffAssumptions; customer snapshots may also include the exact optional continuationState returned by a prior complete run. Every snapshot must contain at least one event. For each container, promisedEta, freeTimeEnd, or at least one matching event supplies its comparison anchor. Tariff values are your own USD/day assumptions; the Actor does not consult terminal calendars or carrier tariffs.

Raw JSON is checked before parsing for the 2,097,152-byte limit and duplicate object keys. Event time must be no later than receipt time, and both must be no later than the Actor-generated decision time. Unsafe references and secret-shaped output-bearing values become non-echoing row errors.

{
  "watchId": "customer-watch-1",
  "mode": "snapshot",
  "sourceStatus": "complete",
  "rightsAttestation": {
    "customerControlsOrIsAuthorizedToUseData": true,
    "noCredentialsOrSecretsSubmitted": true,
    "unfetchedReferencePolicyAccepted": true,
    "attestedAt": "2026-08-09T09:00:00Z",
    "attestorId": "customer-operator-1"
  },
  "containers": [{
    "containerNumber": "MSCU1234566",
    "carrier": "customer-declared-carrier",
    "promisedEta": "2026-08-12T12:00:00Z",
    "freeTimeEnd": "2026-08-15T12:00:00Z",
    "originUnlocode": "NLRTM",
    "destinationUnlocode": "USLAX"
  }],
  "events": [{
    "eventId": "customer-event-1",
    "containerNumber": "MSCU1234566",
    "eventType": "gate_in",
    "eventTime": "2026-08-08T09:00:00Z",
    "receivedAt": "2026-08-08T09:05:00Z",
    "locationUnlocode": "NLRTM",
    "plannedLocationUnlocode": null,
    "plannedTime": null,
    "source": "customer-system",
    "reference": "ref:customer-evidence-1"
  }],
  "tariffAssumptions": { "currency": "USD", "demurragePerDay": 0, "detentionPerDay": 0 }
}

Pricing

Pay per event: USD 0.005 Actor start plus one container-exception-found event for a complete report containing one or more new material exception rows. A report with 1, 2 or 1,000 material rows still emits exactly one result event. Baselines, unchanged reports, partial/error reports and the synthetic demo emit zero product events. Tier discounts are Apify's account tiers: FREE, BRONZE, SILVER, GOLD, PLATINUM and DIAMOND. The price is selected by the charging manager, never by row count.

The direct Hub reference price is USD 0.0800. The local product contract caps the worst FREE run at USD 0.0550 and requires p95 whole-run COGS of no more than USD 0.0100 before external release.

Delivery and recovery

Production reads the authoritative input exactly once from the default KVS client as getRecord("INPUT", { buffer: true }). It validates the original Buffer size, JSON media type, fatal UTF-8/ASCII decoding and duplicate keys before schema processing. Parsed Actor.getInput() values, alternate input keys and inbound metamorph records are unsupported.

The SDK does not expose an account tier. The Actor infers one tier only from an exact accepted apify-actor-start/container-exception-found price pair. Pinned apify@3.7.2 exposes exactly those configured PPE keys; apify-default-dataset-item is an implicit zero-priced SDK operation and is not added to the pricing registry. A successful unpriced push returns aggregate chargedCount=1, one Dataset item, configured chargeability keys only, default counter delta +1, report counter delta 0 and amount delta 0. A paid named Dataset push confirms one product result only when the pinned SDK returns aggregate chargedCount=2, exact +1 report/default counters, one Dataset item and the exact integer micro-USD report-price amount delta. Chargeability is capacity evidence only. Either boolean post-charge limit flag is accepted; true means only that future report capacity is exhausted. Extra, missing or malformed configured pricing keys fail closed. replay.status is the one closed set not_replay | confirmed_replay | output_recovered | ambiguous_replay.

For a customer snapshot, the Actor performs at most one Dataset push: an unpriced decision payload for baseline/unchanged/partial/error, or one Actor.pushData(decisionPayload, "container-exception-found") call when a complete snapshot contains a material exception. Application retries are zero. An ambiguous response is terminal with nullable delivery facts and DELIVERY_EFFECT_UNKNOWN; it is never pushed again. The only run-scoped KVS record is default OUTPUT, read back before a successful exit. currentRunEffects.stateWrites=0 and intentWrites=0; the caller, not the Actor, persists nextContinuationState.

Direct Apify reruns are new billable runs. The Actor makes no global cross-run billing-deduplication claim and does not use OUTPUT as a replay index. Callers must use requestDigest and the exact continuation state to avoid duplicate orchestration. One monotonic 120-second deadline starts before INPUT acquisition and includes OUTPUT Buffer read-back and exit; the paid push receives at most 30 seconds of the remaining budget.

Limitations and rights

The customer declares control or authorization for the submitted data. DCSA URLs in contract/source-rights.json are citation-only semantic references; no DCSA artifact is bundled or fetched. No carrier, terminal or commercial provider adapter exists in V1. This is not legal advice and does not prove tariff, invoice, carrier or compliance truth.

Related actors

Actor	Relationship
Strait of Hormuz Tanker Flow Recovery	Maritime flow context for separate regional monitoring; this Actor remains container-event-only and does not call it.
Singapore Bunker Tanker Divergence	Separate Singapore market signal; useful as a workflow input only after the customer maps and authorizes its own events.
Panama Canal Queue Transit Imbalance	Separate Panama transit signal; not a carrier truth source for this Actor.

Synthetic public Task

The public Task may use the following exact input inline; it is also kept repo-only in fixtures/public-task-input.json for tests. The runtime accepts only these values, performs zero provider/reference/continuation-state calls, writes one receipt-free REPORTS item and one default KVS OUTPUT, and emits zero product events.

{"watchId":"public-synthetic-demo","mode":"synthetic_demo","sourceStatus":"complete","rightsAttestation":{"customerControlsOrIsAuthorizedToUseData":true,"noCredentialsOrSecretsSubmitted":true,"unfetchedReferencePolicyAccepted":true,"attestedAt":"2026-08-09T00:00:00.000Z","attestorId":"public-task-synthetic"},"containers":[{"containerNumber":"MSCU1234566","carrier":"Synthetic Ocean","billOfLading":null,"bookingNumber":null,"promisedEta":"2026-08-12T12:00:00.000Z","freeTimeEnd":"2026-08-15T12:00:00.000Z","originUnlocode":"NLRTM","destinationUnlocode":"USLAX"}],"events":[{"eventId":"demo-gate-in-1","containerNumber":"MSCU1234566","eventType":"gate_in","eventTime":"2026-08-08T09:00:00.000Z","receivedAt":"2026-08-08T09:05:00.000Z","locationUnlocode":"NLRTM","plannedLocationUnlocode":null,"plannedTime":null,"source":"synthetic-fixture","reference":"ref:demo-1"},{"eventId":"demo-eta-1","containerNumber":"MSCU1234566","eventType":"eta_update","eventTime":"2026-08-09T10:00:00.000Z","receivedAt":"2026-08-09T10:01:00.000Z","locationUnlocode":"NLRTM","plannedLocationUnlocode":null,"plannedTime":"2026-08-12T12:00:00.000Z","source":"synthetic-fixture","reference":"ref:demo-2"}],"tariffAssumptions":{"currency":"USD","demurragePerDay":0,"detentionPerDay":0}}

The authoritative machine result is the following complete default KVS OUTPUT for the inline input above. The timestamps, request identifiers, and SHA-256 values are deterministic for this exact input and generated-at decision time:

{"schemaVersion":"1.1.0","actor":"container-exception-evidence","requestId":"cee_req_c00f36d48fcf6afb14f70cafb8612c13","requestDigest":"sha256:c00f36d48fcf6afb14f70cafb8612c137413baab4f76cebef95ac63645ae4975","reportId":"cee_report_0faa55b5e8a81a852a05985755fdf4f0","decisionPayloadDigest":"sha256:98f2565a695bedd5134d638df03b61c39f109c017157bd51d1b56fe2972acabc","decisionPayloadReference":{"datasetId":"default","reportId":"cee_report_0faa55b5e8a81a852a05985755fdf4f0"},"decisionPayloadReferenceNullReason":null,"status":"complete","resultFound":false,"generatedAt":"2026-08-09T12:00:00.000Z","billing":{"accountTier":"FREE","accountTierSource":"apify_charging_manager","startEvent":{"name":"apify-actor-start","quantity":1,"unitPriceUsd":0.005,"totalPriceUsd":0.005,"priceNullReason":null},"exceptionEvent":null,"exceptionEventNullReason":"SYNTHETIC_DEMO","defaultDatasetEventPriceUsd":0,"defaultDatasetEventPriceNullReason":null,"projectedTotalUsd":0.005,"projectedTotalNullReason":null,"confirmedTotalUsd":0.005,"confirmedTotalNullReason":null,"maxRunSpendUsd":0.055},"deliveryReceipt":{"status":"uncharged","expectedExceptionEvents":0,"confirmedExceptionEvents":0,"confirmedExceptionEventsNullReason":null,"datasetItemsWritten":1,"datasetItemsWrittenNullReason":null,"sdkChargeEvidence":{"aggregateChargedCount":1,"aggregateChargedCountNullReason":null,"eventChargeLimitReached":false,"eventChargeLimitReachedNullReason":null,"chargeableWithinLimitStatus":"default_dataset_only_sufficient"},"receiptDigest":"sha256:fe8dc243f918ee8e4816673b777751bc371322023a9dc4eacb7aac349491ccf0","receiptDigestNullReason":null},"baselineReceipt":{"status":"not_written","initializedContainerCount":0,"initializedContainerCountNullReason":null,"advancedContainerCount":0,"advancedContainerCountNullReason":null,"baselineDigest":null,"baselineDigestNullReason":"NO_BASELINE_WRITE"},"replay":{"status":"not_replay","priorReceiptFacts":null,"priorReceiptFactsNullReason":"NOT_REPLAY"},"currentRunEffects":{"applicationPaidPushInvocations":0,"applicationUnpricedPushInvocations":1,"applicationRetries":0,"datasetItemsWritten":1,"datasetItemsWrittenNullReason":null,"productResultEvents":0,"productResultEventsNullReason":null,"stateWrites":0,"stateWritesNullReason":null,"intentWrites":0,"providerCalls":0,"sdkTransportRetries":null,"sdkTransportRetriesNullReason":"SDK_MANAGED_OPAQUE"},"containers":[{"containerNumber":"MSCU1234566","carrier":"Synthetic Ocean","billOfLadingDigest":null,"bookingNumberDigest":null,"normalizedInputIdentity":"sha256:7395181548a57f76b43eca7276d6a22ede2a85ff9349f789e22223aba5427ad3","observedAt":"2026-08-09T10:01:00.000Z","effectiveAt":null,"generatedAt":"2026-08-09T12:00:00.000Z","status":"synthetic_demo","error":null,"exceptionType":null,"additionalExceptionTypes":[],"severity":"none","materialChange":false,"firstObservedAt":null,"baselineEta":"2026-08-12T12:00:00.000Z","currentEta":"2026-08-12T12:00:00.000Z","delayHours":0,"freeTimeClock":{"status":"active","freeTimeEnd":"2026-08-15T12:00:00.000Z","remainingHours":144,"timezone":"UTC","basis":"customer_supplied","nullReason":null},"costExposure":{"status":"zero","currency":"USD","amount":0,"basis":"customer_supplied_tariff_assumptions","nullReason":null},"evidence":[{"source":"synthetic-fixture","eventId":"demo-gate-in-1","eventType":"gate_in","eventTime":"2026-08-08T09:00:00.000Z","receivedAt":"2026-08-08T09:05:00.000Z","reference":"ref:demo-1","referenceNullReason":null,"eventCoreDigest":"sha256:108a667218e922ba7345e05f04ef6c65cbf5157f7d958ded75a9f9aa46d4b622","digest":"sha256:73082736a674d77b02b201690c78cae31cdedccf10befa92c1e2464478c4c52e"},{"source":"synthetic-fixture","eventId":"demo-eta-1","eventType":"eta_update","eventTime":"2026-08-09T10:00:00.000Z","receivedAt":"2026-08-09T10:01:00.000Z","reference":"ref:demo-2","referenceNullReason":null,"eventCoreDigest":"sha256:ef979b1783236cbe705bb5d85b6957c73a2a3f825580365bd6b30d2d00da3183","digest":"sha256:6471e73b56a811fa1adf607214488e5ccdb569c4b080f238fefe141791367e20"}],"confidence":{"level":"high","score":0.9,"reasons":["COMPLETE_TWO_OR_MORE_SUPPORTING_EVENTS"]},"limitations":["SYNTHETIC_DEMO"],"sourceCompleteness":"complete","freshnessSeconds":7140,"recommendedHumanAction":"none","stateDisposition":"not_written","stateDispositionReason":null,"billingDisposition":"synthetic_demo","acceptedPricingTier":"FREE","nullReasons":{"carrier":null,"billOfLadingDigest":"NOT_SUPPLIED","bookingNumberDigest":"NOT_SUPPLIED","observedAt":null,"effectiveAt":"NO_EXCEPTION","error":"NO_ERROR","exceptionType":"NO_EXCEPTION","firstObservedAt":"NO_EXCEPTION","baselineEta":null,"currentEta":null,"delayHours":null,"freshnessSeconds":null}}],"errors":[],"limitations":["SYNTHETIC_DEMO"],"nextContinuationState":null}

Consumers must read OUTPUT from KVS rather than reconstructing it from prose; this example is included so a machine client can validate the complete shape without accessing the repo-only fixture.

What you get

The paid unit is one complete delivered container-exception evidence report, not one container or one exception row. A report can contain one, two, or up to one thousand material rows while emitting exactly one container-exception-found event.

For each accepted container, the report can include:

• a normalized observation time and customer-controlled identity digest;
• ETA comparison against the caller-carried healthy baseline;
• missing, duplicated, or out-of-order milestone evidence;
• gate-in, gate-out, empty-return, and free-time pairing observations;
• demurrage or detention exposure calculated only from buyer assumptions;
• source completeness and freshness fields;
• evidence rows with stable digests and unfetched references;
• confidence, limitations, and a recommended human action;
• continuation state for the next complete snapshot;
• a receipt-free Dataset decisionPayload for analysis;
• authoritative KVS OUTPUT for delivery, billing, current-run effects, baseline, continuation, and replay reconciliation.

The Actor is deliberately evidence-first. It does not say that a carrier is at fault, an invoice is valid, a tariff applies, a shipment breached a contract, or a customer should dispute a charge. recommendedHumanAction is a review route, not an executed action. No email, webhook, portal message, claim, booking change, or payment is sent.

Free outcomes remain explicit. The fixed synthetic demo writes one unpriced report. A healthy baseline, unchanged complete snapshot, partial source, invalid input, pricing failure, or ambiguous delivery emits no confirmed product event. The automatic Actor start event is separate and may still apply.

Who uses it

Import and export operations teams

Use the report to organize customer-owned event timelines and highlight exceptions that need a person to inspect carrier notices, terminal records, contracts, and operational context.

Freight forwarders and NVOCC operations

Use exact customer shipment snapshots to compare ETA and milestone changes across an approved workflow. The Actor does not establish carrier truth or replace the forwarder's exception-management process.

Finance and accrual teams

Use costExposure only as an arithmetic scenario under buyer-supplied USD/day assumptions. It is not an invoice, accrual policy, accounting conclusion, tariff quote, payable instruction, or recoverability opinion.

Data engineering teams

Use the closed schemas, canonical JSON, domain-separated digests, bounded payloads, and caller-carried continuation state to test upstream container event pipelines. Unknown values remain null with reasons rather than being silently guessed.

Governance and assurance reviewers

Use rights attestations, source completeness, evidence digests, limitations, delivery receipts, and current-run effects to review what the workflow actually did. Customer shipment facts remain unverified unless your separate process proves them.

Automation builders

Use REPORTS for evidence display and KVS OUTPUT for terminal routing. Only route material rows into a human work queue. Never trigger a carrier claim, payment hold, customer representation, legal notice, or booking action directly from this Actor.

How to run

Start with synthetic_demo. It proves input validation, one unpriced Dataset write, default-Dataset accounting, KVS OUTPUT, and the no-provider boundary without using customer shipment information.

For a customer snapshot:

1. export a bounded authorized snapshot from your own system;
2. include at least one container and one event;
3. set sourceStatus truthfully to complete or partial;
4. complete all five rights and unfetched-reference attestations;
5. provide buyer-owned tariff assumptions, including zero when no scenario is required;
6. on the first complete run, omit continuationState and retain the returned nextContinuationState;
7. on the next comparable run, pass that exact state back without editing it;
8. set a charge cap that covers the current start price and one report price;
9. poll the exact run to terminal, then read KVS OUTPUT before REPORTS;
10. preserve and manually reconcile an ambiguous receipt without retrying.

API pattern:

curl -X POST \
  'https://api.apify.com/v2/acts/zinin~container-exception-evidence/runs?token=YOUR_APIFY_TOKEN' \
  -H 'content-type: application/json' \
  --data-binary @container-snapshot.json

The runtime reads the raw default KVS INPUT record exactly once as a Buffer. Do not depend on alternate Input keys, parsed fallback values, metamorph input, or a second read. Keep each request below the byte and count limits. If your system has more rows, partition by a stable watch scope and reconcile each run separately.

Direct reruns are new Apify runs and can incur a new start or result event. The Actor does not persist a cross-run idempotency index. Your orchestrator must bind the request digest and exact continuation state to its own job record.

Input contract

The authoritative contract is contract/input.schema.json plus raw-byte runtime validation. The Store schema is an Apify-compatible projection and cannot express every duplicate-key, byte, time, and cross-field condition.

Root fields

• watchId is a bounded caller-owned workflow identity;
• mode is snapshot or the exact fixed synthetic_demo branch;
• sourceStatus is complete or partial and must reflect the supplied export;
• rightsAttestation is mandatory and closed;
• containers, events, and tariffAssumptions are mandatory;
• continuationState is optional only for a customer snapshot;
• unknown keys fail closed.

Do not put a bill of lading, booking number, customer name, carrier account, credential, or other sensitive value in watchId. It appears in workflow metadata even though sensitive shipment references are digested elsewhere.

Rights attestation

The caller must affirm control or authorization to process the data, absence of credentials and secrets, acceptance of the unfetched-reference policy, a bounded attestation time, and a caller-controlled attestor ID. These are buyer representations, not independently verified legal facts.

Containers

Container number follows the accepted ISO-style shape and must match referenced events. Carrier text is buyer supplied. BOL and booking identifiers are never returned as raw values; when accepted they are represented by domain-separated digests. Origin and destination UN/LOCODE values are syntactically validated but not checked against a port registry.

At least one comparison anchor is required: promised ETA, free-time end, or a matching event. Unknown facts must remain null. Do not substitute placeholder dates or zero values merely to pass validation.

Events

Every event has a stable event ID, matching container number, closed event type, event time, receipt time, source label, and safe ref: or HTTPS reference. References are validated as strings and never fetched. Event time cannot be after receipt time, and neither can be after the Actor-generated decision time.

The Actor does not verify the sender, signature, source clock, carrier system, terminal system, EDI semantics, or authenticity of an event. Use a trusted upstream provenance process when those facts matter.

Tariff assumptions

Only USD/day buyer assumptions are accepted in V1. The Actor applies deterministic arithmetic to the supplied free-time and event timeline. It does not fetch a tariff, terminal calendar, holiday schedule, invoice, exchange rate, contract, or carrier rule. Zero means the buyer intentionally supplied a zero scenario; it does not prove there is no commercial exposure.

Continuation state

nextContinuationState is the complete caller-carried baseline for the next comparable snapshot. Preserve the exact value. Editing, merging, reconstructing, or combining it across watch IDs destroys the accepted comparison boundary. The Actor does not open a named KVS or RequestQueue for customer state.

Happy, partial, and failure output

Complete material exception

The Actor builds one immutable decisionPayload, performs one linked paid push, reconciles Dataset and product/default event counters plus integer micro-USD amount, writes KVS OUTPUT, reads it back, and exits. Confirmation requires the exact pinned receipt lattice; a positive aggregate count alone is insufficient.

Complete healthy baseline or unchanged snapshot

A complete snapshot without a new material exception writes one unpriced decision payload and zero product events. It can return the next continuation state for the caller to retain. An unchanged result is not evidence that every external source or real-world fact is unchanged; it is a comparison of the accepted supplied snapshots.

Partial source

Partial input may produce review evidence but cannot safely advance the same complete-snapshot conclusions. Source completeness remains visible and the output explains why the result is partial. Do not infer that an absent milestone or container is truly missing from the upstream system.

Invalid or unsafe input

Oversize bytes, invalid media type, duplicate JSON keys, invalid encoding, unknown fields, secret-shaped output-bearing values, unsafe references, time inconsistency, and schema failures stop before product delivery. Correct the source rather than coercing it.

Pricing or budget failure

The configured PPE map must contain exactly the start and container-exception-found keys at one accepted tier pair. The implicit default Dataset event is not configured and remains zero priced. Unknown keys, malformed prices, insufficient charge capacity, or unreadable amount/counter state fail closed.

Ambiguous delivery

If a push response is lost or receipt facts cannot prove the side effect, OUTPUT records ambiguity with nullable facts and no automatic retry. Preserve run, Dataset, KVS, logs, request digest, continuation state, and platform counters. Never assume ambiguity means free or paid.

OUTPUT write failure

OUTPUT is authoritative. If it cannot be written and read back, the run fails even when a Dataset effect may exist. Use platform evidence to reconcile the original attempt before starting another run.

Field dictionary

Field group	Meaning	Boundary
requestId / requestDigest	Current deterministic request binding	A new run is not global idempotency
reportId	Stable report identity	Not a carrier or shipment identifier
decisionPayloadDigest	Integrity binding for REPORTS row	A digest is not anonymization
status	Closed processing terminal	Not a legal/commercial verdict
resultFound	Confirmed product-result outcome in OUTPUT	Dataset payload itself has no receipt
billing	Tier, unit, start, projected and confirmed amount facts	Current platform pricing remains authoritative
deliveryReceipt	Dataset/event/amount confirmation lattice	Ambiguous facts prohibit blind retry
baselineReceipt	Caller-carried baseline effect	No named persistence is claimed
replay	Current-run recovery classification	Direct rerun can be newly billable
currentRunEffects	Pushes, retries, rows, events, state and provider calls	Null means unavailable under a closed reason
containers	Per-container deterministic evidence rows	Customer source facts remain unverified
evidence	Accepted supplied timeline facts and digests	References are never fetched
confidence	Confidence in submitted-evidence processing	Not carrier-truth confidence
limitations	Explicit scope and data gaps	Review before downstream use
recommendedHumanAction	Unsent routing suggestion	Never an executed action
sourceCompleteness	Buyer-declared coverage class	Does not prove upstream completeness
freshnessSeconds	Submitted event recency	Depends on buyer timestamps
nextContinuationState	Exact next comparable baseline	Caller must persist unchanged

REPORTS versus OUTPUT

REPORTS stores the immutable payload prepared before the delivery receipt is known. It cannot contain authoritative post-push billing or recovery facts. OUTPUT is the terminal receipt and is the only machine surface for result, delivery, billing, replay, and current-run reconciliation. Do not rebuild OUTPUT from the Dataset row or README example.

Evidence and boundaries

The Actor proves deterministic transformations of submitted bytes. It can prove which rows were accepted, how times were normalized, how exception rules were applied, which assumptions were used, what digests bind the evidence, what the runtime attempted, and what the pinned counters/amounts confirm.

It does not prove carrier, terminal, customs, port, customer, vessel, invoice, tariff, ETA, free-time, contract, negligence, liability, or legal truth. It has no provider key and makes zero carrier, terminal, DCSA, AIS, portal, reference, or nested Actor calls.

DCSA references in the source-rights registry are citation-only semantic context. The runtime does not bundle, fetch, reproduce, or claim conformance to a DCSA product. Customer fields and local rules remain the operative evidence contract.

Privacy and confidentiality

Container events can reveal customer relationships, routes, schedules, delays, commercial terms, and operational patterns. Submit only the minimum authorized fields. Do not submit credentials, access tokens, personal contact data, customs documents, bills of lading in narrative text, dangerous-goods details, security instructions, sanctions-sensitive notes, or other unnecessary confidential data.

Digests reduce raw-value exposure but are not anonymization. Apify retains run Input, REPORTS, OUTPUT, and logs under workspace controls. Establish access, retention, deletion, correction, export, and incident-response rules before production use.

Decision routing

Route by terminal truth first, then evidence:

• confirmed material report: human exception review;
• complete unchanged/baseline result: retain as bounded evidence;
• partial result: repair coverage before operational interpretation;
• invalid input: correct upstream schema or unsafe content;
• pricing/budget failure: review live tier and cap without replaying an ambiguous operation;
• ambiguous delivery: freeze automation and reconcile manually;
• OUTPUT failure: use platform run, Dataset, KVS, logs, and counters as the recovery surface.

Within a confirmed report, use severity, exception type, confidence, limitations, freshness, and recommended action to order a human queue. Never allow one field alone to trigger a material external action.

Commercial playbooks

ETA exception triage

Submit a complete authorized snapshot with promised ETA and recent ETA events. Review deterministic slips and evidence timestamps, then ask an operator to check carrier communications and customer commitments.

Free-time review

Supply the buyer's accepted free-time end and tariff scenario. Treat calculated cost as planning exposure only. A person must verify the applicable tariff, calendar, contract, invoice, and responsibility.

Milestone completeness

Use ordered events to identify missing or out-of-order pairs. Partial source status keeps uncertainty visible. Do not treat a missing supplied event as proof that the real milestone did not occur.

Customer escalation preparation

Use the report to assemble an internal evidence packet. Keep communication, claims, disputes, and customer representations in a separate approved system with human authorization.

Data-pipeline acceptance

Run the synthetic demo and controlled fixtures to validate byte limits, duplicate keys, continuation handling, digests, report schemas, billing counters, and ambiguous recovery before allowing production shipment data.

Integration recipes

Webhook workflow

Wait for one exact run to finish, fetch KVS OUTPUT, validate the schema and receipt, then store a link to the REPORTS row. Send a minimal internal review notification rather than copying shipment evidence into email or chat.

Warehouse workflow

Store one run/OUTPUT record and explode per-container decisions into child rows. Keep the exact next continuation state in a restricted state table keyed by watch ID. Never combine states from different watches or Actor versions.

Ticketing workflow

Create a ticket only for confirmed, reviewable material exceptions. Include the report ID, decision row reference, confidence, limitations, source completeness, and run link. The ticket system owns assignment and resolution; the Actor owns only evidence generation.

MCP workflow

Call only container_exception_evidence.run. Parse the text item and structuredContent as the same canonical OUTPUT. MCP execution does not create an alternative REPORTS contract and must preserve the same input rights and human-review boundaries.

Operating guide

Before production:

• confirm authorization for all container and event data;
• define stable watch ownership and continuation-state storage;
• test the synthetic and controlled snapshot branches;
• document tariff-assumption ownership;
• verify current Apify tier pricing and cap;
• configure access and retention for Input, REPORTS, OUTPUT, and logs;
• assign a human reviewer and correction route.

During a run:

• retain the exact run ID and input digest;
• do not start a second run to poll the first;
• do not edit continuation state;
• allow the 120-second monotonic deadline to govern execution;
• treat REPORTS appearance as evidence preparation, not settlement proof.

After a run:

• check terminal platform status;
• read and validate KVS OUTPUT;
• reconcile result/default counters and confirmed amount;
• inspect completeness, confidence, limitations, and errors;
• persist the next continuation state only from an accepted complete terminal;
• route material evidence to a person;
• apply the approved retention or deletion schedule.

For an incident, preserve the build ID, run ID, Dataset ID, KVS ID, request and payload digests, counters, amounts, logs, continuation state, and exact input hash. Do not overwrite the evidence with a retry.

FAQ

Does it scrape carriers or terminals?

No. It processes customer-authorized snapshots and never fetches references.

Does it verify carrier truth?

No. It validates and transforms submitted evidence under deterministic rules.

Does it calculate an invoice?

No. Cost exposure uses buyer-supplied USD/day assumptions and is a planning scenario, not a payable or recoverable amount.

Why is continuation state caller-carried?

Limited-permissions production deliberately avoids named KVS and RequestQueue state. The caller owns persistence and passes the exact accepted state forward.

Can I rerun safely after an ambiguous push?

Not blindly. A new run can create another start or result event. Reconcile the original run first.

Is one exception row one charge?

No. One complete delivered aggregated report is the result unit whether it has one, two, or one thousand material rows.

Why does the Dataset not contain receipts?

It is written before post-push facts exist. KVS OUTPUT is the authoritative terminal receipt.

Are HTTPS references checked online?

No. Their syntax is validated and the string may be retained, but runtime makes no request.

Does a digest anonymize a BOL or booking value?

No. It avoids returning the raw value but remains linkable evidence and must be protected under your data policy.

What does complete source status mean?

It is a buyer declaration about the submitted snapshot. It is not independent proof that a carrier or terminal source was complete.

Can I automate a dispute or carrier claim?

No. Recommendations are unsent review suggestions. A qualified person must check evidence, contracts, rights, and context.

Is the synthetic demo operational evidence?

No. It is a fixed free contract demonstration only.

Sources and rights

Runtime uses no external provider. All event, container, ETA, free-time, tariff, carrier, and reference facts come from the buyer's submitted snapshot. You must own or be authorized to process, transform, store, and route those facts.

Public accessibility, a portal URL, EDI message, API response, or customer file does not itself grant downstream commercial rights. Retain your licences, contracts, customer instructions, source terms, attribution duties, and data processing records outside the Actor.

The source-rights registry cites public DCSA semantic material as unfetched reference context. No DCSA page or artifact is bundled or called. No carrier, terminal, port, marketplace, AIS, customs, billing, or identity provider is queried. There is no endorsement or official integration claim.

This Actor is not legal advice, a carrier performance rating, a tariff service, an invoice validator, a customs tool, or an automatic claims system. Its narrow claim is that it deterministically transforms a customer-authorized bounded snapshot into evidence, uncertainty, continuation, and current-run receipt facts for human review.