US Brand Evidence Chronology Builder

Build a deterministic US brand evidence chronology from 1-30 closed, normalized evidence rows and an explicit asOf UTC timestamp. The Actor is a local, offline-friendly machine workflow: it sorts submitted facts, marks same-time groups, reports future-dated IDs and basic timestamp warnings, and emits exact counts with stable SHA-256 digests.

What it does

Each row contains only evidenceId, eventType, effectiveAt, observedAt, sourceUrl, and fact. effectiveAt may be null when the submitted row has no effective timestamp. The chronology is sorted by effectiveAt, then observedAt, then evidenceId; rows without effectiveAt sort last. Equal (effectiveAt, observedAt) pairs receive a stable tg-* same-time group ID.

The report marks a row future-dated when its effective or observed timestamp is after asOf. Warnings cover missing effective time, effective time after observation, effective time after asOf, and observation after asOf. The Actor copies submitted facts and URLs. It does not resolve a brand, infer identity, verify a source, infer truth, score evidence, or interpret the fact.

Exact task

The public Task uses fixed timestamps and two rows, so it never reads the current clock. Its input is the same runnable payload shown in the Actor input example, and its deterministic report is available through the run Dataset and OUTPUT record.

Runtime and delivery

The runtime uses Apify SDK 3.7.2, pay-per-event pricing, one confirmed apify-actor-start, and at most one result-found event. It confirms the buyer cap before work, performs exactly one pushData(report, "result-found"), verifies the result counter, and then writes the successful report to KVS key OUTPUT. Validation, budget, push, charge, or output uncertainty writes only the small documented error object when that KVS write succeeds and fails the run; it never claims success.

The result is bounded below 32 KiB. There is no network request, proxy, API key, BYOK, child run, Dataset input, state, replay, queue, cron, or current-clock read. No icon is included in this local builder.

Pricing tiers

Tier	Actor start	Result	Discount
FREE	$0.005000	$0.010000	0%
BRONZE	$0.004750	$0.009500	5%
SILVER	$0.004500	$0.009000	10%
GOLD	$0.004250	$0.008500	15%
PLATINUM	$0.004100	$0.008200	18%
DIAMOND	$0.004000	$0.008000	20%

Public references

These five public references were checked during the local build and describe the runtime, storage, schema, and timestamp conventions:

1. Apify JavaScript SDK
2. Apify Actors
3. Apify Dataset storage
4. JSON Schema specification
5. RFC 3339

Contract files

The three Apify schemas are in .actor/: input, Dataset, and output. Normative input and report schemas, limits, and pricing are in contract/. SPEC.md is the implementation contract for this local builder.

Why a chronology is a product, not formatting

Brand evidence often arrives as screenshots, links, announcements, award rows, offer observations, reviews and regulatory notices assembled by different people. The expensive part is not drawing a timeline. It is producing one stable ordering that another reviewer can reproduce, while preserving what was supplied and refusing to invent what was not.

This Actor gives an analyst a bounded handoff object. Each input row retains its evidence identifier, submitted fact, cited HTTPS URL, effective time and observation time. The output applies one published order, assigns stable same-time groups, exposes timestamp anomalies and computes digests over canonical input and output. Two identical logical inputs produce the same chronology regardless of input order. That makes review notes, downstream diffs and audit attachments easier to reconcile.

The Actor does not decide whether two rows refer to the same brand, whether a publisher is authoritative, whether a fact is true, whether a trademark is owned, or whether conduct is infringing. Those are different products and often qualified judgments. Keeping them outside the chronology prevents a deterministic transformation from becoming a false legal conclusion.

Best-fit users

Brand and marketing operations

Use it to order reviewed campaign, offer, announcement and recall evidence before an internal handoff. The stable report is useful when several teams must discuss the same sequence without each spreadsheet sorting missing timestamps differently.

Competitive-intelligence teams

Use it after collection and normalization to create a reproducible evidence appendix. Keep the source URLs and fact text as observations, then route the report to an analyst who can assess identity, credibility and relevance.

Agencies and consultants

Use one report per client question or evidence packet. The digests show that the submitted packet and delivered chronology have not silently changed between review steps. They do not prove that the source itself was authentic.

Legal and compliance support teams

Use it as an administrative ordering tool under a qualified reviewer’s workflow. It can flag impossible-looking or future-dated timestamps, but it does not calculate deadlines, apply evidentiary rules, determine rights, or give legal advice.

Data engineering teams

Use the closed schema and deterministic digests to test upstream normalization. A rejected row reveals a contract issue before uncertain data enters a broader brand-intelligence pipeline.

Input contract in plain language

One run accepts one object with schemaVersion, asOf and rows. The shape is closed: extra properties are rejected instead of being silently ignored.

Field	Required	Boundary
schemaVersion	yes	Must be 1.0.
asOf	yes	Explicit Gregorian UTC second such as 2026-08-05T09:00:00Z; the Actor never reads the current clock.
rows	yes	Between 1 and 30 unique evidence rows. Input order has no meaning.
evidenceId	yes	Stable unique ID, 1–40 bounded characters. Duplicate IDs reject the request.
eventType	yes	One of announcement, award, offer, recall, regulatory, review, other.
effectiveAt	yes	Explicit UTC timestamp or null when the submitted evidence has no effective time.
observedAt	yes	Explicit UTC timestamp recording when the submitter observed the evidence.
sourceUrl	yes	Bounded credential-free HTTPS URL. It is preserved but not fetched.
fact	yes	Buyer-supplied bounded text, copied without interpretation.

Use effectiveAt: null when the evidence does not state an effective time. Do not substitute the collection time. The Actor sorts missing effective times last and adds missing_effective_at, making the gap visible instead of disguising an estimate as a fact.

Do not put secrets, access tokens or authenticated URLs in sourceUrl. URLs containing credentials are rejected. The Actor does not need an API key, browser cookie or proxy.

Deterministic ordering rules

The chronology uses three keys:

1. effectiveAt, with null values last;
2. observedAt;
3. evidenceId as the stable final tie-breaker.

Rows with the exact same effective and observed timestamps receive the same deterministic sameTimeGroupId. The group means “these submitted timestamps are equal.” It does not mean the events happened simultaneously in the real world, came from the same source, or have equal significance.

sameTimeGroups provides each stable group ID, timestamps, ordered evidence IDs and count. This makes ties explicit for a UI or reviewer. A consumer should not break a same-time tie by importance unless it has a separate, documented rule.

Timestamp warnings

Warnings are structural and deterministic:

Code	Trigger	What to do
missing_effective_at	effectiveAt is null.	Open the cited source and determine whether an effective time exists. Do not invent one.
effective_after_observed_at	Submitted effective time is later than observation time.	Confirm whether the source announced a future effective date or whether a timestamp was entered incorrectly.
effective_after_as_of	Effective time is later than the report boundary.	Treat it as future-dated evidence and review before using the chronology as current state.
observed_after_as_of	Observation time is later than the report boundary.	Correct asOf or the observation time; the row could not have been observed inside the stated boundary.

Warnings do not prove an error. A future offer or scheduled recall may legitimately have an effective time after observation. The report therefore recommends review instead of deleting or rewriting the row.

Decision envelope

The report includes a compact decision layer in addition to the chronology:

Field	Meaning
recordType	Always evidence_chronology for a delivered report.
decisionSchemaVersion	Version of the decision envelope, separate from the closed input contract.
entityId	Stable digest-derived report identity; it does not claim a resolved brand identity.
observedAt	The buyer-supplied asOf boundary, not a hidden current-clock reading.
confidenceScore / confidenceBand	Confidence in deterministic validation, sorting and digest integrity only. It explicitly does not score source truth.
confidenceReasons	Human-readable scope of that narrow confidence score.
sourceEvidence	The submitted evidence ID, URL and observation time, marked buyer_supplied_not_fetched.
dataGaps	Permanent boundaries: no source authentication, brand resolution, truth inference or history.
negativeSignals	Timestamp warning codes plus unverified-source and unresolved-identity flags.
recommendedAction	Open every cited source and obtain qualified review before consequential action.
actionPriority	high when time anomalies exist, otherwise medium.
interpretationBoundary	Explicit list of conclusions the chronology cannot establish.
safeToAutomate	Always false for consequential action.
failureType / retryable	null and false on a successfully delivered deterministic report.
partial	True when the delivered chronology contains timestamp warnings or future-dated rows.
billing	Confirms the one delivered report is the result-found unit.
change	Explicitly unavailable because the Actor reads no previous run or external state.

The confidenceScore is deliberately narrow. A score of 100 means the Actor is confident it applied its deterministic transformation contract to the supplied rows. It does not mean the evidence is true, the source is genuine, the named brand is correct, or a legal claim is strong. Keep confidenceReasons and interpretationBoundary visible whenever the score is shown.

Example decision use

A safe routing rule can be:

if partial == true:
    send to timestamp-resolution queue
else:
    send to source-and-identity review queue

never:
    issue a takedown, accusation, ownership claim or legal notice from this report alone

This is why safeToAutomate remains false even when there are no warnings. A clean chronology is cleanly ordered buyer input, not independently verified evidence.

Digests and reproducibility

inputDigest is computed from canonical normalized input. chronologyDigest covers the ordered chronology. reportDigest covers the report body before the final digest is attached. All are SHA-256 values over canonical JSON.

Use them to:

• detect whether a submitted evidence packet changed between workflow stages;
• confirm that two users received the same ordered chronology;
• key an internal cache or immutable review attachment;
• compare a stored report before initiating a separate diff workflow;
• prove that the UI and API are displaying the same report bytes after canonicalization.

Do not use a digest as proof that a source was authentic. A digest proves consistency of the bytes processed by this Actor, not provenance outside it.

Delivery and billing contract

The Actor requires valid pay-per-event pricing before reading input. It recognizes the documented six tiers and confirms:

• exactly one apify-actor-start charge exists;
• no previous result-found event exists in this run;
• the buyer’s maximum charge covers one result;
• the report remains below the hard output-size limit.

It then performs exactly one linked pushData(report, "result-found"). After delivery it verifies that the result-event counter increased by exactly one, then writes the same successful report to OUTPUT. This order prevents OUTPUT from claiming success before the paid Dataset delivery is confirmed.

If validation, budget, delivery, charge verification or the success OUTPUT write is uncertain, the run fails with a small terminal error object. It never emits a free Dataset row that could be mistaken for a chronology. A delivery_unknown state should be reviewed before retrying because the platform call may have crossed the delivery boundary.

Size and cost planning

The bounded product accepts at most 30 rows and keeps the delivered report below 32 KiB. One successful run produces one result event, regardless of whether the report has 1 or 30 evidence rows. That makes cost predictable for one bounded evidence packet.

Use separate runs when evidence belongs to different matters, clients, brands or review boundaries. Do not pack unrelated material into one report merely to reduce event count; it weakens the meaning of the digest and makes access control harder.

The tier table above is part of the runtime contract. The actual deployed run pricing remains authoritative. If pricing differs from a recognized tier, the Actor fails closed instead of guessing whether it is safe to deliver.

Privacy and security

The Actor makes no network requests. It does not open submitted URLs, read Dataset input, launch child Actors, use proxies, call an LLM, persist a cache, or read previous runs. Its external side effects are the one paid Dataset delivery and terminal OUTPUT write required by the product contract.

Because facts and URLs are buyer-supplied, avoid personal data that is unnecessary for the review purpose. Do not include credentials or private access links. Apify Dataset and key-value-store access, retention and export policies still apply to your run. Configure them according to your organization’s requirements.

Fact text is treated as data. The Actor validates bounds and control characters, normalizes Unicode safely and never executes the content. Source URLs must be HTTPS, have a non-empty host and contain no username or password.

Source rights and lawful use

The caller owns collection and provenance. The Actor does not scrape or copy external pages; it processes the bounded facts and citations supplied in the run. Before submitting or redistributing material, make sure you have the right and lawful purpose to use it. A public URL does not automatically grant rights to copy an entire page or process personal data.

The output preserves citations to support review. It does not grant a license, authenticate a publication, resolve ownership, or establish admissibility. Consult qualified counsel for legal, rights-enforcement or regulatory decisions.

Quality checklist before action

Reviewers should confirm:

• the packet refers to the intended brand or legal entity;
• each source opens and corresponds to the submitted fact;
• each source is authentic and current enough for the decision;
• effective and observation timestamps were transcribed correctly;
• future-dated rows are understood rather than treated as current facts;
• missing effective times remain explicit unless a source supplies them;
• every same-time group is handled without invented ordering;
• the report digests match the stored review attachment;
• partial, negativeSignals and dataGaps are visible;
• qualified review occurs before any enforcement, accusation or consequential action.

Common mistakes

Using a brand name as if it were resolved identity. The Actor receives no brand field and resolves no entity. Keep identity work in a separate verified step.

Treating observedAt as publication time. It records when the submitter observed the evidence. If the source exposes a publication or effective time, map that deliberately and document the choice upstream.

Replacing missing time with asOf. That hides uncertainty. Use null and let the report flag the gap.

Interpreting the confidence score as truth probability. It covers transformation integrity only. The report repeats that boundary so downstream systems do not need to guess.

Automatically retrying an unknown delivery. Inspect the run, Dataset and charge events first. A blind retry may duplicate a paid report when the first delivery outcome is uncertain.

Using chronology order as causal order. The report sorts submitted timestamps. It makes no causal inference and no materiality ranking.

Integration pattern

1. Collect evidence in an authorized upstream process.
2. Normalize each observation into the six-field closed row.
3. Assign a stable evidenceId that survives reordering.
4. Choose an explicit asOf boundary for the review.
5. Run the Actor and retain both Dataset report and OUTPUT.
6. Verify status, partial, counters, warnings and digests.
7. Open each cited source and resolve identity/authenticity questions.
8. Send the reviewed chronology into a separate diff, metrics or action-queue Actor only under your documented policy.

For support, provide the run ID, non-sensitive input packet, terminal error code or delivered report digest. Never send private source credentials because the Actor neither needs nor accepts them.

Related Actors

Use these public Actors to collect, normalize, compare, and act on evidence before or after building a chronology:

Actor	What it adds
US Brand Federal Award Snapshot	Collects bounded official federal-award evidence for a brand workflow.
US Brand Offer Evidence Normalizer	Normalizes buyer-supplied offer observations into stable evidence rows.
US Brand Evidence Snapshot Diff	Compares two normalized evidence snapshots after chronology preparation.
US Brand Signal Metrics Aggregator	Summarizes normalized signal rows into deterministic portfolio metrics.
US Brand Action Queue	Converts reviewed evidence into a bounded, ordered follow-up queue.

These are separate public products. This Actor does not call them or create hidden child-run charges.