Add a feature roadmap and implementation plan for a context evidence artifact
This commit is contained in:
226
docs/roadmap/evidence.md
Normal file
226
docs/roadmap/evidence.md
Normal file
@@ -0,0 +1,226 @@
|
|||||||
|
# Published Evidence Context
|
||||||
|
|
||||||
|
## Status
|
||||||
|
|
||||||
|
Accepted for implementation.
|
||||||
|
|
||||||
|
## Purpose
|
||||||
|
|
||||||
|
Let downstream consumers build narrative reports from normalized artifacts
|
||||||
|
without separately parsing the original transcript or resolving source-unit
|
||||||
|
references themselves.
|
||||||
|
|
||||||
|
The production JSON output optionally publishes one deterministic, deduplicated
|
||||||
|
evidence-context artifact containing the transcript units relevant to explicitly
|
||||||
|
selected normalized lanes. Existing lane payloads remain the canonical semantic
|
||||||
|
results and retain their precise source references.
|
||||||
|
|
||||||
|
## Desired End State
|
||||||
|
|
||||||
|
When evidence-context publication is enabled, a consumer can:
|
||||||
|
|
||||||
|
1. discover one versioned evidence-context document through `index.json`;
|
||||||
|
2. obtain the union of source units needed to understand evidence cited by the
|
||||||
|
selected normalized lanes;
|
||||||
|
3. distinguish each artifact's direct evidence references from surrounding
|
||||||
|
units included only for narrative context;
|
||||||
|
4. retain speaker, timestamp, and other accepted source-unit metadata needed to
|
||||||
|
interpret the transcript; and
|
||||||
|
5. produce a narrative report without receiving duplicated transcript text in
|
||||||
|
every lane payload.
|
||||||
|
|
||||||
|
This is deterministic output projection. It does not invoke an LLM, change
|
||||||
|
normalization, or make surrounding context part of an artifact's evidence.
|
||||||
|
|
||||||
|
## Configuration Policy
|
||||||
|
|
||||||
|
Evidence publication is configured on the production JSON output module. The
|
||||||
|
intended configuration shape is:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
output:
|
||||||
|
module: json
|
||||||
|
options:
|
||||||
|
evidence_context:
|
||||||
|
enabled: true
|
||||||
|
window_units: 3
|
||||||
|
lanes:
|
||||||
|
- combat-turns
|
||||||
|
- item-events
|
||||||
|
- npc-interactions
|
||||||
|
- npcs
|
||||||
|
- spells
|
||||||
|
```
|
||||||
|
|
||||||
|
- Omitting `evidence_context` disables publication. When the object is present,
|
||||||
|
`enabled` is required.
|
||||||
|
- `enabled: false` accepts no `lanes` or `window_units` fields, preventing
|
||||||
|
silently ignored configuration.
|
||||||
|
- `lanes` is a required, non-empty allowlist of configured final lane IDs when
|
||||||
|
evidence publication is enabled. Values are trimmed, unique, and normalized
|
||||||
|
to lexical order.
|
||||||
|
- `window_units` is a non-negative integer and defaults to `3`. Zero publishes
|
||||||
|
only directly referenced units.
|
||||||
|
- Unknown lanes, duplicate lane IDs, and selected lanes whose artifact kind
|
||||||
|
cannot expose source evidence fail configuration resolution or pipeline
|
||||||
|
preparation.
|
||||||
|
- A selected lane that completes without a normalized output contributes no
|
||||||
|
evidence and does not make an otherwise successful run fail.
|
||||||
|
- Invocation-level lane filtering does not invalidate the configured allowlist.
|
||||||
|
Allowlisted lanes excluded from the effective run contribute nothing, while
|
||||||
|
the evidence document still records the configured allowlist.
|
||||||
|
|
||||||
|
The allowlist is intentional safety and stability policy. Scene descriptions
|
||||||
|
and other broad-range lanes are excluded unless named expressly. Adding a new
|
||||||
|
pipeline lane never silently increases output size or publishes more transcript
|
||||||
|
content.
|
||||||
|
|
||||||
|
## Evidence Collection Boundary
|
||||||
|
|
||||||
|
Evidence collection applies to accepted final normalized artifacts from the
|
||||||
|
selected lanes. It must not inspect arbitrary serialized JSON for fields named
|
||||||
|
`source_ref` or `source_refs`, and the generic JSON output module must not
|
||||||
|
depend on D&D artifact types.
|
||||||
|
|
||||||
|
Artifact-kind registrations expose their source references through an explicit
|
||||||
|
typed projection contract. The framework uses that contract to assemble a
|
||||||
|
domain-neutral evidence request containing:
|
||||||
|
|
||||||
|
- the accepted generic source document;
|
||||||
|
- the selected lane and artifact identities; and
|
||||||
|
- defensive copies of their direct source references.
|
||||||
|
|
||||||
|
The output stage owns publication of the resulting logical artifact. Generic
|
||||||
|
framework code owns range validation, position-based expansion, and union
|
||||||
|
logic. Domain-specific adapters own only the extraction of evidence references
|
||||||
|
from their typed artifacts.
|
||||||
|
|
||||||
|
Both plural-reference artifacts and singular-reference artifacts, such as
|
||||||
|
scene descriptions, can participate through the same projection contract.
|
||||||
|
They do so only when their configured lane is allowlisted.
|
||||||
|
|
||||||
|
## Range Expansion And Deduplication
|
||||||
|
|
||||||
|
For every valid direct source reference:
|
||||||
|
|
||||||
|
1. resolve its endpoints through source-document positions, not numeric
|
||||||
|
unit-ID arithmetic;
|
||||||
|
2. expand the range by `window_units` positions on each side;
|
||||||
|
3. clip the expanded range at document boundaries; and
|
||||||
|
4. union overlapping or contiguous expanded ranges.
|
||||||
|
|
||||||
|
Published contexts and units remain in source-document order. Each source unit
|
||||||
|
appears at most once in a merged context. Original direct references remain
|
||||||
|
unchanged and are associated with their contributing lane IDs so consumers can
|
||||||
|
tell why a context was included.
|
||||||
|
|
||||||
|
The projector must not silently omit or repair an invalid reference that
|
||||||
|
reaches this boundary. Such a value violates the accepted normalized-artifact
|
||||||
|
contract and causes output projection to fail with a content-safe error.
|
||||||
|
|
||||||
|
No implicit coverage limit truncates selected evidence. If the allowlisted
|
||||||
|
lanes collectively cite most or all of a transcript, the evidence document may
|
||||||
|
contain most or all of it. The explicit lane allowlist is the control that
|
||||||
|
prevents a broad lane such as scene descriptions from doing so accidentally.
|
||||||
|
|
||||||
|
## Durable Evidence Artifact
|
||||||
|
|
||||||
|
The JSON bundle gains one optional, non-lane artifact with these durable
|
||||||
|
identities:
|
||||||
|
|
||||||
|
| Property | Value |
|
||||||
|
| --- | --- |
|
||||||
|
| Logical file | `evidence-context.json` |
|
||||||
|
| Index descriptor | `evidence_context` |
|
||||||
|
| Artifact kind | `source/evidence-context` |
|
||||||
|
| Media type | `application/json` |
|
||||||
|
| Schema ID | `notarius.source.evidence_context` |
|
||||||
|
| Schema name | `notarius_source_evidence_context_v1` |
|
||||||
|
| Schema version | `v1` |
|
||||||
|
|
||||||
|
The descriptor in `index.json` carries the artifact and schema identities,
|
||||||
|
analogous to the existing chunk-map descriptor. The artifact is present
|
||||||
|
whenever evidence publication is enabled, including when its context collection
|
||||||
|
is empty.
|
||||||
|
|
||||||
|
The document contains:
|
||||||
|
|
||||||
|
- the source document ID and semantic digest;
|
||||||
|
- the effective window size;
|
||||||
|
- the sorted configured lane allowlist;
|
||||||
|
- an ordered context collection;
|
||||||
|
- each context's expanded start and end unit IDs;
|
||||||
|
- the original direct references and contributing lane IDs covered by that
|
||||||
|
context; and
|
||||||
|
- the ordered accepted source units, including unit ID, kind, text,
|
||||||
|
self-reference, and metadata.
|
||||||
|
|
||||||
|
Expanded context bounds are navigation aids, not citations. The original
|
||||||
|
references embedded in each context remain the authoritative direct evidence.
|
||||||
|
The evidence artifact is discovered separately from lane payloads and does not
|
||||||
|
increase the normalized-lane count reported by the runner or subprocess
|
||||||
|
receipt.
|
||||||
|
|
||||||
|
## Failure And Publication Semantics
|
||||||
|
|
||||||
|
- Evidence projection occurs only after selected normalized outputs are known
|
||||||
|
and before the output encoder returns its logical files.
|
||||||
|
- Projection or encoding failure is an output-stage framework error; the CLI
|
||||||
|
does not publish a partially assembled output bundle.
|
||||||
|
- Rejected or absent lane outputs contribute nothing. Their attempted values
|
||||||
|
and source references must not be published through this artifact.
|
||||||
|
- Context generation is deterministic for the same source document, selected
|
||||||
|
normalized outputs, lane allowlist, and window size.
|
||||||
|
- Existing output, checkpoint, warning, rejection, debug, and subprocess
|
||||||
|
success semantics remain unchanged.
|
||||||
|
|
||||||
|
## Sensitivity And Size
|
||||||
|
|
||||||
|
Unlike the current chunk map, the evidence artifact contains transcript text
|
||||||
|
and source-unit metadata. Enabling it therefore creates additional durable
|
||||||
|
sensitive data and may materially increase bundle size.
|
||||||
|
|
||||||
|
The implemented configuration, operations, integration, and consumer documents
|
||||||
|
state that:
|
||||||
|
|
||||||
|
- evidence publication is opt-in;
|
||||||
|
- output permissions and retention must be appropriate for source content;
|
||||||
|
- selecting broad or numerous lanes can publish most of the transcript; and
|
||||||
|
- the artifact must not contain raw input bytes, LLM prompts or responses,
|
||||||
|
auxiliary reference content, credentials, debug-only data, or filesystem
|
||||||
|
paths.
|
||||||
|
|
||||||
|
## Acceptance Criteria
|
||||||
|
|
||||||
|
- Evidence publication is disabled by default and leaves existing bundles
|
||||||
|
unchanged.
|
||||||
|
- Enabling it requires an explicit non-empty lane allowlist.
|
||||||
|
- References from all selected successful lanes contribute to one deduplicated
|
||||||
|
document.
|
||||||
|
- Non-monotonic unit IDs are expanded and ordered correctly by document
|
||||||
|
position.
|
||||||
|
- Overlapping windows share one ordered copy of each included source unit.
|
||||||
|
- Direct references remain distinguishable from added context.
|
||||||
|
- Scene descriptions cannot contribute unless their lane is explicitly
|
||||||
|
allowlisted.
|
||||||
|
- Invalid selected lanes and unsupported artifact kinds fail before execution;
|
||||||
|
invalid accepted references fail output projection rather than being ignored.
|
||||||
|
- Empty selected-lane results produce a valid empty evidence artifact.
|
||||||
|
- Existing D&D lane schemas, normalized-output counts, and source-reference
|
||||||
|
semantics do not change.
|
||||||
|
- Generic framework and output packages do not depend on D&D types or parse
|
||||||
|
artifact JSON heuristically.
|
||||||
|
- The published contract and operational documentation clearly describe source
|
||||||
|
sensitivity, discovery, compatibility, and retention.
|
||||||
|
|
||||||
|
## Out Of Scope
|
||||||
|
|
||||||
|
- Embedding transcript units directly into each D&D record or lane payload.
|
||||||
|
- Replacing precise source references with expanded context ranges.
|
||||||
|
- Automatically including every configured lane.
|
||||||
|
- An explicit full-transcript publication mode.
|
||||||
|
- LLM summarization, retrieval, ranking, or narrative generation.
|
||||||
|
- Per-record window sizes or lane-specific window sizes.
|
||||||
|
- CLI overrides for evidence configuration.
|
||||||
|
- Reading rejected attempts, debug artifacts, auxiliary references, or prior
|
||||||
|
output bundles as evidence sources.
|
||||||
@@ -1,284 +1,486 @@
|
|||||||
# Subprocess Integration Implementation Plan
|
# Published Evidence Context Implementation Plan
|
||||||
|
|
||||||
## Status
|
## Status
|
||||||
|
|
||||||
Completed.
|
Ready for implementation.
|
||||||
|
|
||||||
## Objective
|
## Objective
|
||||||
|
|
||||||
Implement the accepted [Subprocess Integration Contract](subprocess.md) as a
|
Implement the accepted [Published Evidence Context](evidence.md) roadmap as an
|
||||||
small, generic extension of the existing CLI boundary. The completed work must
|
optional, deterministic extension of the production JSON output. The completed
|
||||||
let a subprocess caller discover a successful Notarius output bundle through a
|
work must publish one deduplicated source-context artifact for an explicit set
|
||||||
versioned JSON receipt without parsing human prose, while preserving current
|
of successful normalized lanes while leaving existing lane payloads,
|
||||||
pipeline, output, rejection, warning, configuration, and interactive CLI
|
normalization, checkpointing, subprocess results, and disabled output bundles
|
||||||
behavior.
|
unchanged.
|
||||||
|
|
||||||
Complete the stages below in order. Each stage must leave its affected package
|
Complete the stages below in order. Each stage must leave its affected packages
|
||||||
passing before the next begins. Do not add Narratio-specific production code,
|
passing before the next begins. Do not implement per-record hydration, implicit
|
||||||
a public Go client, a new output encoder, or any feature listed as out of scope
|
all-lane collection, a full-transcript mode, LLM processing, or any other
|
||||||
in the feature roadmap.
|
roadmap item marked out of scope.
|
||||||
|
|
||||||
## Decisions And Invariants
|
## Decisions And Invariants
|
||||||
|
|
||||||
- `--json` is a boolean flag on `notarius run`; it does not affect pipeline
|
- Evidence publication is output policy. Normalizers continue to return
|
||||||
resolution, execution, checkpoint identity, output encoding, or publication.
|
semantic artifacts with precise source references and do not receive
|
||||||
- The machine result is a private CLI Go type implementing the public
|
hydration responsibilities.
|
||||||
`notarius.run-result.v1` wire contract. Do not expose framework or CLI Go
|
- The framework operates on the accepted generic `source.SourceDocument` and
|
||||||
packages for external import.
|
typed artifact projections. It must not inspect serialized JSON for
|
||||||
- The finalized run manifest is authoritative for `run_id`, `pipeline_id`, and
|
`source_ref` or `source_refs`, and generic packages must not depend on D&D
|
||||||
`validation_status`. Verify that its pipeline ID matches the effective
|
types.
|
||||||
resolved pipeline rather than emitting conflicting provenance.
|
- The selected lane allowlist is explicit, non-empty, and globally addressed by
|
||||||
- Human-oriented stdout remains byte-for-byte governed by its current path when
|
resolved lane ID. Pipeline resolution already guarantees lane IDs are unique
|
||||||
`--json` is absent. Machine mode emits no human status or debug-path line on
|
across ordered steps.
|
||||||
stdout.
|
- The framework decodes accepted serialized normalize outputs through their
|
||||||
- Warnings and errors remain on stderr. Exit statuses remain 0 for success, 1
|
registered artifact codecs before invoking typed evidence projectors. This
|
||||||
for runtime failure, and 2 for syntax failure.
|
supports both fresh and checkpoint-reused normalize outputs without retaining
|
||||||
- Validation rejection remains a successful pipeline outcome. The receipt
|
a second typed result channel.
|
||||||
reports counts but does not decide which lanes an orchestrator requires.
|
- Expansion uses source-document positions. Numeric unit IDs are identities,
|
||||||
- The receipt points to the existing bundle; it does not duplicate output
|
not sequence numbers.
|
||||||
descriptors, lane payloads, warnings, rejections, or manifest content.
|
- Direct source references are never widened or rewritten. Expanded ranges are
|
||||||
- Reported filesystem paths are lexical absolute paths produced with
|
context bounds only.
|
||||||
`filepath.Abs`. Do not resolve symlinks or change the physical directories
|
- Rejected, failed, and absent normalized lane outputs contribute no evidence.
|
||||||
used for publication.
|
- Evidence output is sensitive durable source content, not cache or debug
|
||||||
- For the production `json` output module, `index_file` is exactly
|
state. It contains accepted source units only and never raw input bytes,
|
||||||
`index.json` and is included only after confirming that the runner returned
|
prompts, model responses, auxiliary references, paths, or credentials.
|
||||||
exactly one logical file with that clean name. For any injected or future
|
- The optional `evidence_context` index field is an additive v1 JSON-bundle
|
||||||
non-`json` output module, omit `index_file`; the machine receipt remains
|
change. Existing D&D artifact schemas and the subprocess receipt do not
|
||||||
generic.
|
change.
|
||||||
- Machine-result construction and JSON encoding occur before debug success
|
|
||||||
terminalization, but stdout writing occurs only after output publication and
|
|
||||||
successful requested debug terminalization.
|
|
||||||
- Standard output is not transactional. A final writer failure returns exit 1
|
|
||||||
and may leave partial bytes. Consumers must ignore stdout unless the process
|
|
||||||
exits 0. Because debug terminalization must precede receipt emission, a
|
|
||||||
result-delivery failure does not rewrite an already persisted successful run
|
|
||||||
report; it is additionally reported on stderr and the process exits 1.
|
|
||||||
- Do not add a stable JSON error envelope or promote diagnostic wording into a
|
|
||||||
compatibility contract.
|
|
||||||
|
|
||||||
## Stage 1: Define The Run-Result Wire Model
|
## Stage 1: Add Typed Evidence Capability And Resolve Output Policy
|
||||||
|
|
||||||
Add a focused private implementation under `internal/cli`, preferably
|
Add a dedicated artifact-evidence registry under the pipeline framework:
|
||||||
`run_result.go`, with:
|
|
||||||
|
|
||||||
- a constant for `notarius.run-result.v1`;
|
- `pipeline.ArtifactEvidenceRegistry` stores one typed projector per artifact
|
||||||
- a private result struct whose JSON fields and requiredness match the feature
|
kind.
|
||||||
roadmap;
|
- `pipeline.ArtifactEvidenceProjector[T]` is
|
||||||
- a constructor that accepts the resolved pipeline, completed runner output,
|
`func(T) []source.SourceRef`.
|
||||||
run output directory, and optional debug directory; and
|
- `pipeline.RegisterArtifactEvidence[T](registry, kind, projector)` accepts a
|
||||||
- serialization into an owned byte slice containing exactly one compact JSON
|
non-empty kind and non-nil projector, records the exact Go type for `T`, and
|
||||||
object followed by one newline; and
|
rejects duplicate kinds.
|
||||||
- a complete-write helper for delivering those prepared bytes.
|
- The erased projection boundary checks the exact registered type, invokes the
|
||||||
|
projector, and returns a defensive copy of its references.
|
||||||
|
- The registry exposes only the discovery and projection operations required by
|
||||||
|
resolution, preparation, and execution; do not expose its mutable entries.
|
||||||
|
|
||||||
The result fields are:
|
Add the registry to `pipeline.Registries` and `pipeline.ModuleCatalog`, including
|
||||||
|
CLI catalog conversion, production construction, empty-set detection, and
|
||||||
|
test registry helpers. A nil evidence registry remains valid when evidence
|
||||||
|
publication is disabled. Production construction and the D&D registrar require
|
||||||
|
and populate it.
|
||||||
|
|
||||||
- required `schema_version`, `run_id`, `pipeline_id`, `output_directory`,
|
Define these framework-level output-policy contracts:
|
||||||
`normalized_output_count`, `rejected_output_count`, and `warning_count`;
|
|
||||||
- required non-empty `validation_status`, copied without reinterpretation from
|
|
||||||
the final run manifest;
|
|
||||||
- optional `index_file`, set to `index.json` for the resolved production JSON
|
|
||||||
output module; and
|
|
||||||
- optional `debug_directory`, present only when debug capture was requested and
|
|
||||||
its path is non-empty.
|
|
||||||
|
|
||||||
The constructor must:
|
```go
|
||||||
|
type EvidenceContextPolicy struct {
|
||||||
|
Enabled bool
|
||||||
|
WindowUnits int
|
||||||
|
LaneIDs []string
|
||||||
|
}
|
||||||
|
|
||||||
1. validate the required run ID, pipeline ID, final validation status, and
|
type EvidenceContextPolicyProvider interface {
|
||||||
non-empty run output directory rather than emit a malformed receipt;
|
EvidenceContextPolicy() EvidenceContextPolicy
|
||||||
2. verify that the final manifest pipeline ID matches the effective resolved
|
}
|
||||||
pipeline ID;
|
```
|
||||||
3. convert the output bundle and optional debug bundle paths to lexical absolute
|
|
||||||
paths;
|
|
||||||
4. derive all counts from the completed `pipeline.RunOutput`;
|
|
||||||
5. identify the output module through the resolved module key, not concrete
|
|
||||||
encoder types or D&D knowledge; and
|
|
||||||
6. for module key `pipeline.DefaultOutputModule`, verify exactly one returned
|
|
||||||
logical output file is named `index.json` before setting `index_file`.
|
|
||||||
|
|
||||||
Treat a missing or duplicate `index.json` from the production JSON output as a
|
Provider and prepared-pipeline boundaries defensively copy `LaneIDs`.
|
||||||
runtime contract error. Do not inspect or decode the index contents here; the
|
|
||||||
output encoder and its existing tests own that format.
|
|
||||||
|
|
||||||
Implement the writer with `encoding/json` and complete-write handling. It must
|
Add an optional output-profile option-validation callback to
|
||||||
surface encoding errors, zero-progress writes, short writes, and underlying
|
`OutputEncoderRegistry`:
|
||||||
writer errors to the command boundary. The command must map a delivery failure
|
|
||||||
to a fixed, bounded result-write error without wrapping caller-supplied writer
|
|
||||||
text into user or debug diagnostics. Do not add an injected serializer or a
|
|
||||||
generic serialization framework merely to manufacture unreachable error cases
|
|
||||||
for tests.
|
|
||||||
|
|
||||||
Add lean focused tests for the wire-model boundary:
|
```go
|
||||||
|
type OutputProfileOptionContext struct {
|
||||||
|
LaneIDs []string
|
||||||
|
}
|
||||||
|
|
||||||
- required fields, counts, schema identity, and compact newline-terminated JSON;
|
type OutputProfileOptionValidator func(
|
||||||
- blank required manifest identities, blank validation status, and a mismatch
|
OutputProfileOptionContext,
|
||||||
between final-manifest and effective pipeline IDs;
|
map[string]any,
|
||||||
- lexical absolute conversion for relative output and debug paths;
|
) error
|
||||||
- production JSON entry-point discovery;
|
```
|
||||||
- omission of `index_file` for a non-JSON output module;
|
|
||||||
- missing and duplicate production entry points; and
|
|
||||||
- a representative failing or zero-progress writer.
|
|
||||||
|
|
||||||
Decode structured output in tests rather than snapshotting an entire JSON
|
Add `RegisterBuilderWithProfileValidation(spec, validateOptions,
|
||||||
string. Assert literal field names and the schema identity because they are the
|
validateProfile, builder)` and make existing output registration methods
|
||||||
public compatibility contract.
|
delegate to it with no profile callback. The registry passes defensive copies
|
||||||
|
to validation. The callback receives the complete configured lane-ID set before
|
||||||
|
invocation-level `--only` filtering. The production JSON output uses it only to
|
||||||
|
prove that every configured evidence lane exists. Keep the extension generic:
|
||||||
|
the pipeline supplies lane identities, while the output module interprets its
|
||||||
|
own options. Build that lane set from the normalized legacy-or-steps profile
|
||||||
|
before selection and reject duplicate configured lane IDs through the existing
|
||||||
|
pipeline identity rules.
|
||||||
|
|
||||||
|
Extend the production JSON output options with the nested
|
||||||
|
`evidence_context` object:
|
||||||
|
|
||||||
|
- omission disables the feature;
|
||||||
|
- `enabled` is required when the object is present;
|
||||||
|
- `enabled: false` permits no `lanes` or `window_units` fields;
|
||||||
|
- `enabled: true` requires a non-empty `lanes` array;
|
||||||
|
- lane values are strings, trimmed, non-empty, unique after trimming, and
|
||||||
|
normalized to lexical order;
|
||||||
|
- `window_units` is an optional non-negative integer with default `3`; and
|
||||||
|
- outer and nested unknown fields and incompatible YAML value types remain
|
||||||
|
strict configuration errors.
|
||||||
|
|
||||||
|
The JSON encoder implements the policy provider from its decoded immutable
|
||||||
|
options. Pipeline resolution invokes its profile validator against all
|
||||||
|
configured steps, so an unknown evidence lane fails even when another lane is
|
||||||
|
selected with `--only`.
|
||||||
|
|
||||||
|
During `pipeline.Prepare`, after constructing the output encoder:
|
||||||
|
|
||||||
|
1. obtain and defensively normalize an enabled policy;
|
||||||
|
2. intersect its configured IDs with the effective prepared lanes, treating
|
||||||
|
allowlisted lanes removed by invocation-level filtering as inactive;
|
||||||
|
3. require an artifact-evidence registration for each active lane kind;
|
||||||
|
4. prove that its projector Go type exactly matches the active lane's registered
|
||||||
|
artifact codec type; and
|
||||||
|
5. retain an immutable private evidence plan on `PreparedPipeline`.
|
||||||
|
|
||||||
|
Duplicate or empty provider values, a missing evidence registry for an active
|
||||||
|
lane, unsupported active artifact kinds, and type mismatches fail preparation
|
||||||
|
with pipeline/output/lane context. A disabled or non-participating output
|
||||||
|
encoder creates no evidence plan and preserves existing preparation behavior.
|
||||||
|
The private plan retains both the full configured allowlist for publication and
|
||||||
|
the active lane/projector intersection for execution.
|
||||||
|
|
||||||
|
Register D&D evidence projectors for all six current artifact kinds. Each
|
||||||
|
projector returns copies of the artifact's direct references in record order:
|
||||||
|
spells, NPCs, combat turns, item events, NPC interactions, and the singular
|
||||||
|
reference from each scene description. Scene descriptions gain capability but
|
||||||
|
remain excluded unless their configured lane ID is allowlisted.
|
||||||
|
|
||||||
|
Stage tests:
|
||||||
|
|
||||||
|
- Registry tests cover nil, blank, duplicate, exact-type, defensive-copy, and
|
||||||
|
deterministic discovery behavior.
|
||||||
|
- JSON option tests cover disabled, enabled/default-window, explicit zero
|
||||||
|
window, normalization, duplicates, unknown fields, and invalid types.
|
||||||
|
- Preparation tests cover selected lanes across steps, unknown lanes,
|
||||||
|
unsupported kinds, projector/codec type mismatch, disabled behavior, and
|
||||||
|
defensive policy ownership.
|
||||||
|
- Resolution/preparation tests prove a valid allowlist survives `--only`, an
|
||||||
|
excluded lane contributes no active projector, and a genuinely unknown
|
||||||
|
configured lane still fails profile resolution.
|
||||||
|
- D&D registration tests prove every production D&D artifact kind has the
|
||||||
|
expected evidence capability without testing individual field loops
|
||||||
|
redundantly.
|
||||||
|
- One table-driven D&D projector test supplies representative values for all
|
||||||
|
six artifact kinds and proves plural and singular references are copied
|
||||||
|
without aliasing or semantic rewriting.
|
||||||
|
|
||||||
Stage completion:
|
Stage completion:
|
||||||
|
|
||||||
- `go test ./internal/cli`
|
- `go test ./internal/framework/pipeline`
|
||||||
|
|
||||||
## Stage 2: Integrate Machine Mode With Run Finalization
|
|
||||||
|
|
||||||
Update the run command in `internal/cli/run.go`:
|
|
||||||
|
|
||||||
- register `--json` with the existing `flag.FlagSet`;
|
|
||||||
- include it in root usage without adding it to `runFlagTakesValue`;
|
|
||||||
- leave all existing flag combinations valid; and
|
|
||||||
- do not add configuration or environment equivalents.
|
|
||||||
|
|
||||||
After the runner succeeds and requested debug summaries have been written,
|
|
||||||
apply this exact finalization order:
|
|
||||||
|
|
||||||
1. when `--json` is selected, construct and encode the complete receipt into
|
|
||||||
owned memory; fail before physical output publication if its required fields
|
|
||||||
or production entry point are invalid;
|
|
||||||
2. publish the runner's logical output files through the existing confined
|
|
||||||
output writer;
|
|
||||||
3. terminalize requested debug reporting as successful and stop without
|
|
||||||
writing stdout if terminalization fails;
|
|
||||||
4. in machine mode, write the prepared receipt to stdout and return a runtime
|
|
||||||
failure if that write does not complete;
|
|
||||||
5. otherwise, use the unchanged human-oriented success reporting path; and
|
|
||||||
6. report successful-run warning counts to stderr as today.
|
|
||||||
|
|
||||||
The receipt's `output_directory` is the absolute path to the run-specific
|
|
||||||
bundle, not the configured output root. `debug_directory` is the absolute path
|
|
||||||
to the allocated run-specific debug bundle.
|
|
||||||
|
|
||||||
On a machine-result stdout failure after terminalization:
|
|
||||||
|
|
||||||
- report a fixed, bounded, code-owned result-write error on stderr through the
|
|
||||||
existing CLI failure reporting surface without including the underlying
|
|
||||||
writer error;
|
|
||||||
- include the existing debug-path discovery line when applicable;
|
|
||||||
- return exit 1;
|
|
||||||
- do not attempt terminal reporting a second time; and
|
|
||||||
- leave the successfully published output and debug bundle intact.
|
|
||||||
|
|
||||||
Do not change `pipelineCommandState`, the debug run-report wire shape, the
|
|
||||||
output encoder contract, or `writeOutputFiles` solely to support this feature.
|
|
||||||
The machine receipt belongs to CLI reporting after the runner and output module
|
|
||||||
have completed their existing responsibilities.
|
|
||||||
|
|
||||||
Stage completion:
|
|
||||||
|
|
||||||
- `go test ./internal/cli`
|
|
||||||
|
|
||||||
## Stage 3: Protect The Public CLI Contract
|
|
||||||
|
|
||||||
Add or extend behavior-level CLI tests at the narrowest stable boundaries.
|
|
||||||
Reuse existing production components, fakes, state harnesses, and maintained
|
|
||||||
examples rather than creating a second subprocess fixture framework.
|
|
||||||
|
|
||||||
Cover:
|
|
||||||
|
|
||||||
- a representative maintained production invocation with `--json`, decoding
|
|
||||||
exactly one stdout document and verifying the schema identity, run and
|
|
||||||
pipeline IDs, absolute output directory, `index_file`, counts, validation
|
|
||||||
status, and the existence of the referenced bundle entry point;
|
|
||||||
- a warning-bearing debug run, proving a correct warning count, warning
|
|
||||||
reporting on stderr, an absolute optional debug path, and no human prose in
|
|
||||||
stdout;
|
|
||||||
- a rejection-bearing successful run using an explicit deterministic rejecting
|
|
||||||
validator, proving zero or partial normalized outputs and the correct
|
|
||||||
rejection count without changing exit status;
|
|
||||||
- one representative syntax failure and one representative runtime failure
|
|
||||||
with `--json`, proving the established exit class, stderr ownership, and no
|
|
||||||
completed success document;
|
|
||||||
- an injected stdout writer failure after successful publication, proving exit
|
|
||||||
1, retained output files, fixed diagnostic reporting, and omission of a
|
|
||||||
recognizable writer-error sentinel from stderr and debug diagnostics; and
|
|
||||||
- the existing no-`--json` tests continuing to protect interactive output.
|
|
||||||
|
|
||||||
For the writer-failure case, use a writer that fails before accepting bytes when
|
|
||||||
asserting empty stdout. The public contract nevertheless remains that arbitrary
|
|
||||||
writers may leave partial bytes and consumers must ignore stdout on nonzero
|
|
||||||
exit.
|
|
||||||
|
|
||||||
Do not:
|
|
||||||
|
|
||||||
- duplicate the JSON output encoder's lane, manifest, warning, or rejection
|
|
||||||
serialization matrix;
|
|
||||||
- assert complete human error strings;
|
|
||||||
- add a golden file for the small receipt;
|
|
||||||
- test private helper call order; or
|
|
||||||
- add a prompt-language or unrelated end-to-end test.
|
|
||||||
|
|
||||||
Stage completion:
|
|
||||||
|
|
||||||
- `go test ./internal/cli`
|
|
||||||
- `go test ./internal/modules/generic/output/json`
|
- `go test ./internal/modules/generic/output/json`
|
||||||
- `go test ./internal/modules/integration`
|
- `go test ./internal/modules/dnd/register`
|
||||||
|
- `go test ./internal/cli`
|
||||||
|
|
||||||
## Stage 4: Publish The Consumer-Facing Documentation
|
## Stage 2: Define And Build The Evidence-Context Artifact
|
||||||
|
|
||||||
After the code and behavior tests pass, update the canonical current-behavior
|
Add a domain-neutral `internal/framework/evidencecontext` package that owns the
|
||||||
documentation:
|
durable model, JSON Schema, strict codec, projection algorithm, and these exact
|
||||||
|
identities:
|
||||||
|
|
||||||
- `docs/cli.md`
|
- artifact kind `source/evidence-context`;
|
||||||
- add `--json` to run syntax and its flag table;
|
- media type `application/json`;
|
||||||
- define stdout/stderr behavior and the requirement to parse machine stdout
|
- schema ID `notarius.source.evidence_context`;
|
||||||
only after exit 0;
|
- schema name `notarius_source_evidence_context_v1`; and
|
||||||
- preserve the existing exit-status table and link to the run-result
|
- schema version `v1`.
|
||||||
contract.
|
|
||||||
- `docs/integrations/run-result.md`
|
|
||||||
- own the complete `notarius.run-result.v1` field table, requiredness,
|
|
||||||
example, path semantics, production `index_file` rule, partial-write rule,
|
|
||||||
and additive compatibility policy;
|
|
||||||
- link to the published JSON bundle contract rather than repeating its
|
|
||||||
descriptors or payload schemas.
|
|
||||||
- `docs/integrations/json-output.md`
|
|
||||||
- add only a narrow cross-link explaining that a subprocess caller obtains
|
|
||||||
the physical bundle root from the run-result receipt before using
|
|
||||||
`index.json` for logical discovery;
|
|
||||||
- do not duplicate run-result fields or stream semantics.
|
|
||||||
- `docs/consumers/subprocess.md`
|
|
||||||
- provide a concise task workflow for preflight, invocation, separate stream
|
|
||||||
capture, exit checking, receipt decoding, confined index resolution, lane
|
|
||||||
lookup by ID, media-type and schema-identity checks, required-versus-optional
|
|
||||||
consumer policy, provenance retention, and sensitive-data handling;
|
|
||||||
- use a generic orchestrator example with placeholders, not private Narratio
|
|
||||||
paths, credentials, or a duplicate complete configuration.
|
|
||||||
- `docs/internal/cli.md`
|
|
||||||
- document receipt construction before publication, emission after
|
|
||||||
publication and debug terminalization, and the stdout failure behavior;
|
|
||||||
- preserve the CLI composition-root boundary.
|
|
||||||
- `README.md` and `docs/development.md`
|
|
||||||
- add only the smallest links needed to make subprocess consumer guidance and
|
|
||||||
its implementation owner discoverable.
|
|
||||||
|
|
||||||
Do not otherwise change `docs/config.md`, `docs/operations.md`, or the JSON
|
Use these package-level model and build contracts:
|
||||||
output bundle contract unless implementation reveals an actual change to
|
|
||||||
behavior they own. The machine receipt adds no configuration field, filesystem
|
|
||||||
surface, retention policy, or lane-output shape.
|
|
||||||
|
|
||||||
After all code, tests, and current-behavior documentation are complete:
|
```go
|
||||||
|
type Document struct {
|
||||||
|
SourceID string
|
||||||
|
SourceDigest string
|
||||||
|
WindowUnits int
|
||||||
|
SelectedLanes []string
|
||||||
|
Contexts []Context
|
||||||
|
}
|
||||||
|
|
||||||
- change [the feature roadmap](subprocess.md) status to `Implemented`;
|
type Context struct {
|
||||||
- change this plan's status to `Completed`; and
|
ContextRef source.SourceRef
|
||||||
- ensure neither roadmap is used as the canonical description of current
|
EvidenceRefs []EvidenceRef
|
||||||
behavior.
|
Units []source.SourceUnit
|
||||||
|
}
|
||||||
|
|
||||||
|
type EvidenceRef struct {
|
||||||
|
LaneID string
|
||||||
|
SourceRef source.SourceRef
|
||||||
|
}
|
||||||
|
|
||||||
|
type LaneEvidence struct {
|
||||||
|
LaneID string
|
||||||
|
SourceRefs []source.SourceRef
|
||||||
|
}
|
||||||
|
|
||||||
|
type BuildRequest struct {
|
||||||
|
Source *source.SourceDocument
|
||||||
|
WindowUnits int
|
||||||
|
SelectedLanes []string
|
||||||
|
LaneEvidence []LaneEvidence
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Apply the JSON field names shown below. Provide `Build(BuildRequest)`,
|
||||||
|
`Serialize(BuildRequest)`, and a `Codec` with the same identity/encode/decode
|
||||||
|
responsibilities as the chunk-map codec.
|
||||||
|
|
||||||
|
The v1 payload has this exact shape:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"source_id": "session-alpha",
|
||||||
|
"source_digest": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
|
||||||
|
"window_units": 0,
|
||||||
|
"selected_lanes": ["npcs"],
|
||||||
|
"contexts": [
|
||||||
|
{
|
||||||
|
"context_ref": {
|
||||||
|
"source_id": "session-alpha",
|
||||||
|
"start_unit_id": 13,
|
||||||
|
"end_unit_id": 13
|
||||||
|
},
|
||||||
|
"evidence_refs": [
|
||||||
|
{
|
||||||
|
"lane_id": "npcs",
|
||||||
|
"source_ref": {
|
||||||
|
"source_id": "session-alpha",
|
||||||
|
"start_unit_id": 13,
|
||||||
|
"end_unit_id": 13
|
||||||
|
}
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"units": [
|
||||||
|
{
|
||||||
|
"id": 13,
|
||||||
|
"kind": "transcript_segment",
|
||||||
|
"text": "The party meets Rowan.",
|
||||||
|
"ref": {
|
||||||
|
"source_id": "session-alpha",
|
||||||
|
"start_unit_id": 13,
|
||||||
|
"end_unit_id": 13
|
||||||
|
}
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
All displayed fields are required. `selected_lanes`, `contexts`,
|
||||||
|
`evidence_refs`, and `units` encode as arrays rather than `null`; `contexts`
|
||||||
|
may be empty. Each unit uses the existing `source.SourceUnit` JSON shape with
|
||||||
|
required `id`, `kind`, `text`, and `ref`, plus optional JSON-shaped `metadata`.
|
||||||
|
Fixed objects reject unknown fields; metadata remains an arbitrary JSON object.
|
||||||
|
|
||||||
|
The builder accepts the validated source document, selected lane IDs, effective
|
||||||
|
window, and lane-attributed direct references, then:
|
||||||
|
|
||||||
|
1. requires a non-negative window and a non-empty, trimmed, unique selected
|
||||||
|
lane set, then stores that set in lexical order;
|
||||||
|
2. requires every `LaneEvidence.LaneID` to belong to the selected set;
|
||||||
|
3. validates the source document, recomputes its semantic digest, and requires
|
||||||
|
it to equal `SourceDocument.Digest`;
|
||||||
|
4. validates every direct reference against one `source.DocumentIndex`;
|
||||||
|
5. deduplicates exact `(lane_id, source_ref)` contributions;
|
||||||
|
6. resolves endpoints to document positions;
|
||||||
|
7. expands each side without integer overflow and clips at document bounds;
|
||||||
|
8. sorts by expanded document position with deterministic lane/reference
|
||||||
|
tie-breakers;
|
||||||
|
9. merges overlapping or position-contiguous expanded intervals;
|
||||||
|
10. unions and deterministically sorts each merged context's direct
|
||||||
|
contributions; and
|
||||||
|
11. deep-clones the corresponding source units and JSON-shaped metadata.
|
||||||
|
|
||||||
|
Contexts are disjoint and ordered by document position, so a source unit occurs
|
||||||
|
at most once in the document. `context_ref` identifies the first and last
|
||||||
|
included units; `evidence_refs` retains only original citations. An empty
|
||||||
|
reference collection produces the same source identity, window, sorted
|
||||||
|
allowlist, and an explicit empty contexts array.
|
||||||
|
|
||||||
|
Projection failures identify only structural scope such as lane and reference
|
||||||
|
position. They must not include source text, metadata values, raw serialized
|
||||||
|
artifacts, or unrelated paths.
|
||||||
|
|
||||||
|
The codec must validate its model before encoding, produce deterministic JSON,
|
||||||
|
strictly decode the checked-in schema, and return independently owned values.
|
||||||
|
The JSON output encoder remains responsible for pretty-printing the logical
|
||||||
|
file with its standard trailing newline. Follow the existing chunk-map
|
||||||
|
package's separation between model, builder, codec, schema asset, and contract
|
||||||
|
tests where useful, without coupling the two artifact formats.
|
||||||
|
|
||||||
|
Stage tests:
|
||||||
|
|
||||||
|
- A table-driven builder suite covers zero and nonzero windows, boundary
|
||||||
|
clipping, non-monotonic unit IDs, separate gaps, overlapping and contiguous
|
||||||
|
windows, duplicate contributions, multiple lanes, stable ordering, empty
|
||||||
|
contexts, invalid selected/contributing lanes, source-digest mismatch, and
|
||||||
|
invalid references.
|
||||||
|
- Ownership tests prove output mutation cannot affect the source document or
|
||||||
|
projector inputs, including nested metadata.
|
||||||
|
- Codec tests cover round trip, required arrays, schema identity, malformed and
|
||||||
|
trailing JSON, unknown fixed fields, invalid ordering/ranges, mismatched
|
||||||
|
source identities, and independently owned decoded metadata.
|
||||||
|
- Use structured assertions and a compact valid fixture; do not add a large
|
||||||
|
transcript golden file.
|
||||||
|
|
||||||
Stage completion:
|
Stage completion:
|
||||||
|
|
||||||
- validate documentation links and command examples against the implementation;
|
- `go test ./internal/framework/evidencecontext`
|
||||||
|
|
||||||
|
## Stage 3: Integrate Projection With Runner Output
|
||||||
|
|
||||||
|
Extend `contracts.OutputRequest` with an optional
|
||||||
|
`EvidenceContext *SerializedArtifact` field and clone it at every ownership
|
||||||
|
handoff, following the existing chunk-map pointer pattern.
|
||||||
|
|
||||||
|
After lane execution and final manifest population, but before invoking the
|
||||||
|
output encoder, the runner must:
|
||||||
|
|
||||||
|
1. skip all work when the prepared evidence plan is absent;
|
||||||
|
2. index accepted `NormalizeOutputs` by their globally unique lane IDs and fail
|
||||||
|
on an internal duplicate rather than silently overwrite it;
|
||||||
|
3. for each selected lane with an output, verify its source and artifact kind,
|
||||||
|
decode it through the prepared artifact codec registry, and invoke the
|
||||||
|
prepared typed projector;
|
||||||
|
4. build and serialize the evidence document through the evidence-context
|
||||||
|
package; and
|
||||||
|
5. pass a defensive serialized-artifact copy to the output encoder.
|
||||||
|
|
||||||
|
Selected lanes without normalized output contribute nothing. Normalize
|
||||||
|
rejections remain successful pipeline outcomes; evidence projection does not
|
||||||
|
inspect rejected candidates. An invalid accepted reference, incompatible
|
||||||
|
serialized artifact, projection type failure, or evidence serialization failure
|
||||||
|
is an output-stage framework error before logical files are returned or
|
||||||
|
physically published.
|
||||||
|
|
||||||
|
At this external-content consumption boundary, do not propagate artifact-codec
|
||||||
|
or metadata-cloning errors with `%w` when their text could contain artifact
|
||||||
|
fields or source metadata. Return fixed, actionable categories scoped by lane
|
||||||
|
and operation; detailed codec errors remain available to direct trusted
|
||||||
|
callers and their focused tests.
|
||||||
|
|
||||||
|
Add an allowlisted debug summary containing only evidence artifact identity,
|
||||||
|
selected lanes, window, context count, unit count, and source digest. Do not
|
||||||
|
duplicate transcript text or source-unit metadata into a new evidence-specific
|
||||||
|
debug envelope. Existing normalized-output debug behavior remains unchanged.
|
||||||
|
|
||||||
|
The output artifact is not a normalized lane, generated reference, checkpoint,
|
||||||
|
or manifest normalized-output entry. It does not alter normalized-output,
|
||||||
|
rejection, or warning counts. Resume continues to reuse normalized checkpoints;
|
||||||
|
evidence is deterministically rebuilt during the always-executed output stage.
|
||||||
|
|
||||||
|
Stage tests:
|
||||||
|
|
||||||
|
- Runner tests use a real codec, evidence projector, and small capturing output
|
||||||
|
encoder to prove selected-lane union, absent/rejected lane omission, invalid
|
||||||
|
accepted-reference failure, output-request defensive ownership, and no work
|
||||||
|
when disabled.
|
||||||
|
- Include one checkpoint-reused normalized-output case to prove evidence is
|
||||||
|
reconstructed identically without retaining typed normalize values.
|
||||||
|
- Confirm projection failures prevent output encoding and return a failed
|
||||||
|
manifest without changing rejection semantics.
|
||||||
|
|
||||||
|
Stage completion:
|
||||||
|
|
||||||
|
- `go test ./internal/framework/pipeline`
|
||||||
|
|
||||||
|
## Stage 4: Publish Through The JSON Bundle
|
||||||
|
|
||||||
|
Teach the production JSON encoder to recognize the optional evidence-context
|
||||||
|
artifact, verify its exact kind, media type, schema identity, schema digest, and
|
||||||
|
payload validity through the evidence-context codec, and emit:
|
||||||
|
|
||||||
|
- logical file `evidence-context.json`; and
|
||||||
|
- optional `index.json` descriptor field `evidence_context`.
|
||||||
|
|
||||||
|
The descriptor uses the same six fields as `chunk_map`:
|
||||||
|
`artifact_kind`, `file`, `media_type`, `schema_id`, `schema_name`, and
|
||||||
|
`schema_version`. Refactor the encoder's private descriptor representation only
|
||||||
|
as needed to share that shape; do not change the existing `chunk_map` wire
|
||||||
|
contract. Evidence output is ordered with the encoder's other fixed logical
|
||||||
|
files, remains a non-lane artifact, and is present with an empty contexts array
|
||||||
|
when enabled but no selected lane produces references.
|
||||||
|
|
||||||
|
The JSON encoder's validation boundary returns a fixed content-safe evidence
|
||||||
|
artifact error rather than propagating decoder or schema diagnostics that could
|
||||||
|
echo transcript text or metadata. Direct evidence-context codec tests retain
|
||||||
|
detailed structural errors.
|
||||||
|
|
||||||
|
Update the maintained complete D&D configuration to enable evidence context
|
||||||
|
with window `3` for `item-events`, `npcs`, `spells`, `combat-turns`, and
|
||||||
|
`npc-interactions`. Deliberately omit `scene-descriptions`. Keep the minimal
|
||||||
|
configuration disabled by omission.
|
||||||
|
|
||||||
|
Stage tests:
|
||||||
|
|
||||||
|
- JSON encoder tests own descriptor shape, exact logical filename, identity
|
||||||
|
checking, empty evidence publication, and disabled bundle stability.
|
||||||
|
- One assembled production D&D test uses multiple selected lanes with
|
||||||
|
overlapping references and non-monotonic unit IDs, decodes the published
|
||||||
|
artifact through its production codec, and proves union/deduplication and
|
||||||
|
scene-description exclusion.
|
||||||
|
- A second narrow case explicitly allowlists a scene-description lane to prove
|
||||||
|
capability is opt-in rather than hard-coded exclusion.
|
||||||
|
- Existing index, chunk-map, lane, manifest, warning, and rejection tests remain
|
||||||
|
the owners of their current formats; do not repeat their full matrices.
|
||||||
|
|
||||||
|
Stage completion:
|
||||||
|
|
||||||
|
- `go test ./internal/modules/generic/output/json`
|
||||||
|
- `go test ./internal/modules/dnd/...`
|
||||||
|
- `go test ./internal/modules/integration`
|
||||||
|
- `go test ./internal/cli`
|
||||||
|
|
||||||
|
## Stage 5: Publish Current-Behavior Documentation
|
||||||
|
|
||||||
|
After implementation and behavioral tests pass, update canonical documentation:
|
||||||
|
|
||||||
|
- `docs/config.md` owns the nested JSON output options, defaults, strict
|
||||||
|
validation, required lane allowlist, and a small configuration snippet.
|
||||||
|
- A new `docs/integrations/evidence-context.md` owns the complete v1 payload,
|
||||||
|
identities, direct-evidence versus context semantics, ordering,
|
||||||
|
compatibility, and a compact valid example.
|
||||||
|
- `docs/integrations/json-output.md` owns the optional logical file and
|
||||||
|
`index.json` descriptor; link to the evidence contract rather than repeating
|
||||||
|
its payload.
|
||||||
|
- `docs/operations.md` owns durable source-content sensitivity, permissions,
|
||||||
|
retention, and the possibility that selected lanes cover most of a
|
||||||
|
transcript.
|
||||||
|
- `docs/consumers/subprocess.md` explains discovery through the optional index
|
||||||
|
descriptor and requires consumers to treat `evidence_refs`, not expanded
|
||||||
|
context bounds, as citations.
|
||||||
|
- `docs/policy/architecture.md` records the generic typed evidence-projection
|
||||||
|
boundary and output ownership without adding D&D or wire-format detail.
|
||||||
|
- `docs/internal/pipeline.md` and `docs/internal/modules.md` describe the typed
|
||||||
|
evidence registry, preparation checks, reconstruction from serialized
|
||||||
|
normalize outputs, and output-stage ownership without restating public wire
|
||||||
|
fields.
|
||||||
|
|
||||||
|
Update only the smallest orientation links needed for discoverability. Do not
|
||||||
|
add a CLI flag, configuration environment override, or duplicate the complete
|
||||||
|
configuration outside `examples/`.
|
||||||
|
|
||||||
|
After all current-behavior documentation is accurate:
|
||||||
|
|
||||||
|
- set [the feature roadmap](evidence.md) status to `Implemented`;
|
||||||
|
- set this plan's status to `Completed`; and
|
||||||
|
- leave the integration and configuration documents, not either roadmap, as
|
||||||
|
the canonical implemented contract.
|
||||||
|
|
||||||
|
Final verification:
|
||||||
|
|
||||||
- `git diff --check`
|
- `git diff --check`
|
||||||
- `go test ./...`
|
- `go test ./...`
|
||||||
- `go vet ./...`
|
- `go vet ./...`
|
||||||
- `go build ./cmd/notarius`
|
- `go build ./cmd/notarius`
|
||||||
- `go test -race ./internal/cli`
|
- `go test -race ./internal/framework/evidencecontext ./internal/framework/pipeline ./internal/modules/generic/output/json ./internal/modules/dnd/... ./internal/modules/integration ./internal/cli`
|
||||||
|
|
||||||
## Open Questions
|
## Open Questions
|
||||||
|
|
||||||
None. The decisions above resolve stdout partial-write behavior, output-module
|
None. The plan fixes the configuration shape and defaults, typed projection
|
||||||
generality, path normalization, partial pipeline success, terminal reporting,
|
boundary, preparation timing, durable schema and identities, range-union
|
||||||
documentation ownership, and test boundaries.
|
algorithm, failure semantics, JSON discovery, D&D coverage, documentation
|
||||||
|
ownership, and test boundaries.
|
||||||
|
|||||||
Reference in New Issue
Block a user