Project a deterministic realization and provenance report

[woksin]

Scope

Project the existing contribution/resolution pipeline into a versioned deterministic realization report outside .play. Reuse AdapterContribution, Evidence, diagnostics, resolved graph, descriptors/admission and derivation lineage.

Independent dimensions:

• purpose: businessMeaning, realization, operations, uncertain;
• disposition: represented, reportOnly, notRepresented, unresolved, rejected;
• category: eventModelGap, realization, operations, uncertainty.

Emit semantic, realization and byte fingerprints. Preserve stable project/source/subject/fact identities, evidence and generated-artifact links without absolute paths or source excerpts.

Acceptance criteria

• Canonical schema/serializer and compatibility policy.
• Deterministic bytes under adapter/project/fact permutation.
• Technical facts never alter semantic equality.
• Only confirmed eventModelGap can feed Screenplay language admission.
• Full source ranges/outcomes/subjects/producers survive.
• CLI can render text/JSON/report-file without mixing .play stdout.

Depends on #21, #23 and #19; child of #17.

[woksin]

Screenplay #139 and #148 now require implementation requirement/attachment identities in bidirectional evidence. Generated manifests should permit exact recovery of accepted attachments; hand-written source may contribute a located role/body proposal without claiming full semantic understanding. The realization report must distinguish authored, generated, recovered, unsupported, ambiguous, and lossy details, while keeping source identities separate from semantic and attachment identities.

[woksin]

Dependency-ready composition map from the current released pipeline:

• AdapterContribution already preserves producer identity, raw facts, and adapter diagnostics.
• Every GenerationFact carries stable fact/subject identities plus Evidence; evidence already retains producer, strength, stable source-file identity, display range, and explanation.
• ResolvedApplicationGraph already preserves canonical resolved variants/evidence, conflicts, atomic specification admission, and diagnostics. It should remain the semantic-resolution input, not become the report envelope itself.
• GeneratedScreenplayDefinition currently exposes source, syntax, resolved graph, and diagnostics but has no versioned report fragment or independent fingerprints.
• CLI already owns package/assembly/source-policy compatibility provenance and text/JSON diagnostic envelopes in ScreenplayGenerationProvenance and ScreenplayDiagnosticsWriter; those are CLI-owned inputs to composition, not fields Generation should absorb.

Implementation boundary after #25/#26:

1. Add a versioned Generation-owned report fragment projected from frozen contributions + resolved graph + lowering outcomes, with explicit purpose/disposition/category values and canonical ordering.
2. Compute semantic, realization, and final-byte fingerprints from separately defined canonical projections so technical evidence cannot alter semantic equality.
3. Retain full stable identities/ranges/outcomes/producers, but exclude physical roots and source excerpts.
4. Expose canonical serialization plus compatibility policy from Generation; leave the CLI to assemble this fragment beside its existing provider/package/source-policy envelope and to choose text/JSON/report-file output.
5. Prove adapter/project/fact permutation, unknown-fragment preservation at the CLI envelope, and .play stdout isolation.

Implementation-requirement/attachment and generated-artifact links should be init-only/versioned additions when the owning Screenplay contracts exist; source, semantic, attachment, candidate, and runtime identities must remain separate.

[cratis-stagehand]

Thanks for opening this - it has been received and will be looked at.

---

Posted by Stagehand (AI) - an autonomous agent, not a person. Review accordingly.

[woksin]

Ordering clarification after Generation 0.16.0: #23 is complete; this report should follow #19 so it projects frozen adapter runs plus derivation lineage. Screenplay #139 requirement/attachment links are additive future fragment fields, not a blocker for the core versioned report. CritterStack #44 is a sibling downstream lane, not a prerequisite for the report contract.

[woksin]

Architecture reconciliation after Generation 0.17

Independent contract/adversarial reviews agree that #24 is a one-way, one-run projection and must not serialize existing AdapterRunSnapshot, ResolvedApplicationGraph, GeneratedScreenplayDefinition, Canonical or Structural records as its wire format.

Accepted API direction: a separate additive GenerateReport(frozen snapshot, generation options, report options) pipeline in the core Generation package, sharing one resolve/lower/verify pass and returning a deeply immutable versioned report plus canonical bytes. Adapter contracts do not construct reports; no Stage dependency.

The canonical schema has disjoint projections:

• meaning — represented portable business semantics only;
• realization — accepted fact/source/derivation/resolution/lowering/generated-artifact links;
• operations/uncertainties — considered/probed/executed/rejected/conflicted/loss observations.

Fingerprints are independently versioned: Screenplay-owned ESM semantic revision where available, canonical realization SHA-256, exact generated .play UTF-8 SHA-256, and detached report-byte SHA-256. Equal represented meaning is not a completeness verdict; loss/disposition remains explicit.

Canonical bytes exclude free-form evidence explanations, probe descriptions, diagnostic messages, exceptions, stack traces, source excerpts and physical paths. Unsafe normative paths/identities stop emission instead of redaction. Direct/derived origin is independent from disposition; normative fact roster is final direct records plus derived records exactly once; lineage inputs are resolved by FactId rather than positionally zipped with evidence.

Owned Screenplay #137/#167/#139 references are omitted from report v1 unless their owner publishes an exact opaque envelope; Generation never derives them. #38 evidence ingestion/admission remains a separate schema/release/code path.

Two current 0.17 correctness blockers are now focused publicly: #50 removes realization files from semantic equality; #51 replaces diagnostic-prose FactId parsing with typed links. They are required Wave 0 before report schema/fingerprint implementation.

Implementation order: #50/#51 characterization+fix -> report contracts/classification -> one-pass projection and frozen coverage -> explicit meaning/realization projectors -> canonical writer/strict observational reader/fingerprints -> generated links/docs/current+legacy package consumers. Every wave gets permutation/privacy/hostile vectors and independent GPT review.