When was the choice made?
The decision timestamp is the boundary. Context must satisfy the contract without knowledge that arrived later.
Evaluator guide · Exact public evidence
Inspect the clocks before licensing the checker.
This guide turns the public v1 contract and synthetic reports into a buyer-readable evaluation path: what the tool sees, which rule produced each finding, what remains private, and what no result can prove.
Mental model
One row can be historically true and still unavailable to the decision.
When did the described thing occur?
Event time supports backward matching, but event time alone is insufficient when publication or revision happens later.
When could the value be known?
The selected context must have an availability timestamp no later than the decision timestamp.
When was the interval complete?
An aggregate whose period ends after the decision is incomplete even if its row already appears in a file.
The auditor requires event and availability columns to be distinct. An optional period-end column adds a completeness check; a declared maximum age limits how far backward a safe context may be carried.
02 / Contract map
Declare the policy before reading the result.
The strict Draft 2020-12 contract names only contained relative files and the columns needed to make the temporal policy explicit. Unknown properties are rejected.
Decision dataset
Name the boundary rows.
- dataset_idA portable identifier used in aggregate evidence.
- path + formatA contained relative UTF-8 CSV or JSON Lines file.
- timestamp_columnThe RFC 3339 decision time for each row.
- entity_columnsThe keys that prevent unrelated entities from matching.
- expected interval + anchorOptional grid checks for off-cadence decision timestamps.
Context datasets
Separate occurrence from knowability.
- event_time_columnWhen the described event occurred.
- available_time_columnWhen that value could be used by a decision.
- period_end_columnOptional end of the interval represented by the row.
- max_age_secondsMaximum permitted age of the nearest availability-safe match.
- entity and grid fieldsThe same explicit keying and optional cadence model used by decisions.
Resource limits
Bound the local read before execution.
max_file_bytes and max_rows_per_dataset are required. Version 1 caps a declared file at 1,000,000,000 bytes and rows per dataset at 10,000,000; buyers should choose materially lower limits suited to their environment.
03 / Clock interpretation probe
Rank declared clocks without converting a ranking into truth.
The v1.1.0 probe compares candidate timestamp interpretations with an explicit RFC 3339 reference series using entity-isolated, backward-only matches within a declared tolerance.
Candidate modes
The operator supplies the hypothesis set.
- EXPLICIT_RFC3339Read timestamps that already carry a UTC designator or numeric offset.
- NAIVE_FIXED_OFFSETInterpret naive clock text under a declared offset from −840 to +840 minutes.
- NAIVE_IANA_ZONEInterpret naive text under a named zone available to the local Python timezone database.
No mode is inferred from the data. Unknown fields, duplicate interpretation IDs, unavailable zones, path escape, symbolic-link input, and oversized contracts or files are rejected.
Matching and classification
Coverage uses only backward reference matches.
Raw candidate timestamp keys are deduplicated within each entity. The denominator retains unique malformed values so parse failures reduce coverage rather than disappearing. Results are ranked by coverage basis points, then classified as DOMINANT, AMBIGUOUS, INSUFFICIENT_COVERAGE, or REFERENCE_INVALID under the declared minimum coverage and non-zero runner-up gap.
Daylight-saving handling
Ambiguous and nonexistent local times stay visible.
An IANA-zone interpretation counts and excludes local times that map to two instants or no instant. It does not silently choose a fold or shift a nonexistent time. Results depend on the timezone database installed with the local runtime and can change after timezone-rule updates.
python -m temporal_boundary_auditor probe-clock contract.json --out clock-output04 / Synthetic audit evidence
Compare a quiet report with a report that earns its failure.
Both public reports are complete deterministic aggregate outputs from synthetic inputs. Neither contains customer data, private datasets, source paths, or row values.
Clean case
Three decisions, three safe matches, zero findings.
The clean report is PASS. All three decisions find context available by decision time and within maximum age. Leakage, revision ambiguity, incomplete-period, stale-context, and missing-context counts are zero.
status: PASS · findings: 0
matched_within_max_age_count: 3
event_only_join_would_leak_count: 0
period_not_complete_count: 0 · safe_context_too_old_count: 0Contract SHA-2564CBEF0E245734EDB82E77A0C348D0F19B6297F3E754B72282AF3DF8365D42FF8
Adversarial case
Three decisions expose two errors and one warning.
- ERROR · EVENT_ONLY_JOIN_WOULD_LEAK · 1An event-time-only backward join would select one row that was not yet available.
- ERROR · PERIOD_NOT_COMPLETE · 1One selected context row describes a period ending after decision time.
- WARN · SAFE_CONTEXT_TOO_OLD · 1One availability-safe row exists but exceeds the declared maximum age.
The report is FAIL because at least one finding has ERROR severity. The audit itself completed normally.
Contract SHA-256C932073DD245643BDEAFE8A3151A18F4F1A92D66EC8B2BC1BFDDFBD40D161ACF
05 / Output semantics
One audit, three retained interfaces.
The licensed CLI publishes into a new output directory only. Existing output paths are not overwritten.
Files
Complete, streaming, and human-readable views.
- audit.jsonThe complete schema-identified aggregate report: version, contract hash, input identities, counts, joins, findings, status, policy, and limits.
- findings.jsonlOne canonical JSON finding per line for streaming consumers. A clean audit produces an empty file.
- summary.mdA compact operator-readable summary of status, inputs, join counts, findings, and limitations.
Exit behavior
Separate audit findings from invalid operation.
0Completed with no error-severity findings; WARN findings may remain.
2Completed with at least one error-severity finding.
1Invalid contract, input, output location, or operation.
Privacy and identity
Retain byte identity without echoing data.
Each input record includes dataset ID, format, byte count, row count, column names, and SHA-256. Hashes identify the evaluated bytes but are not signatures, timestamps, provenance attestations, or evidence that the bytes were authorized or correct.
Buyer answers
Seven questions to settle before requesting a license.
These answers match the current v1.1.0 offer and public evaluation boundary.
Does a public synthetic report mean the implementation is public?
No. The schemas and synthetic evaluation records are public, but the implementation, wheel, commercial archive, tests, and reference inputs are private licensed delivery assets and are not published to GitHub.
Which data files does version 1.1.0 read?
Version 1.1.0 reads local UTF-8 CSV and JSON Lines files named by contained relative paths in a strict contract. Parquet is not included in version 1.1.0.
Does PASS prove that every form of temporal leakage is absent?
No. PASS means the supplied bytes produced no findings under the supplied contract and implemented mechanical rules. It does not establish complete lineage, factual correctness, causality, statistical validity, compliance, production safety, or fitness for use.
Does a DOMINANT clock-probe result prove the candidate timestamp timezone?
No. DOMINANT means the top caller-declared interpretation met the supplied coverage and runner-up-gap thresholds. Reference completeness, record density, tolerance, entities, omitted modes, daylight-saving transitions, and the local timezone database can change the ranking.
Are datasets uploaded or retained?
No. The licensed runtime makes no network requests, uploads, telemetry calls, or credential requests. Public evaluation pages do not accept datasets.
Should a buyer send sample data before purchase?
No. Purchase intake prohibits datasets, credentials, private source code, customer data, regulated data, and material the requester is not authorized to disclose. Only non-sensitive billing and runtime-format details are requested.
What does the one-organization license permit?
It permits perpetual internal use of the delivered version by one purchasing legal entity, including internal installation, testing, business use, backups, and contractor use solely for that entity under protective confidentiality and license terms. Redistribution, sublicensing, resale, publication, public hosting, and third-party service-bureau use are prohibited.
Ready to decide?