Update native operations, consumer migration, and version checks

This commit is contained in:
2026-11-22 06:32:22 +00:00
parent 5e58327032
commit 2c27695df9
18 changed files with 675 additions and 967 deletions

View File

@@ -1,9 +1,9 @@
# Accepted Chunk Map
This document defines the optional durable `chunk-map.json` artifact in a
[published JSON bundle](json-output.md). It describes the accepted,
materialized chunk plan used by one run. It is not a lane payload and is never
an input to a later pipeline step.
[published JSON bundle](json-output.md). It describes the materialized chunk
plan used by one run, including a supported qualified fallback. It is not a lane
payload and is never an input to a later pipeline step.
## Contract Identity
@@ -16,8 +16,8 @@ an input to a later pipeline step.
| Schema name | `notarius_source_chunk_map_v1` |
| Schema version | `v1` |
The optional `chunk_map` descriptor in `index.json` identifies this artifact.
Export is controlled by the JSON output binding described in
Read this logical path directly when enabled and available; no discovery
descriptor is required. Export is controlled by the JSON output binding in
[Configuration](../config.md#module-bindings-and-validators).
## Wire Shape
@@ -30,7 +30,7 @@ Every payload has these required fields:
| `source_digest` | Lower-case `sha256:` digest of that source document. |
| `plan_digest` | Lower-case `sha256:` digest of the logical chunk plan. |
| `requested_chunker` | Chunk module selected by the resolved pipeline. |
| `producer` | Original accepted-plan producer. `input_module` and `chunk_module` are required; `llm_profile` is optional. |
| `producer` | Current run's plan component selections. `input_module` and `chunk_module` are required; `llm_profile` is optional and applies only to an LLM-backed chunker. Not historical cache execution provenance. |
| `plan_annotations` | Plan-level annotation namespace map; `{}` when none are present. |
| `chunks` | Non-empty execution-order chunk collection. |
@@ -47,9 +47,11 @@ valid JSON and are retained without interpreting a module-specific namespace.
`chunks` are in execution order. Their indexes are contiguous, start at zero,
and equal their array positions; chunk IDs are unique. The emitted map is built
only after the selected plan has been accepted and materialized against the
source document, so its ranges, unit counts, annotations, and digests describe
that exact plan.
after the selected plan has been materialized against the source document,
so its ranges, unit counts, annotations, and digests describe that exact plan.
Supported fallback still satisfies those invariants without asserting ordinary
semantic approval; run-level qualification belongs to the
[CLI report](../cli.md#completion-report).
The codec rejects malformed JSON, trailing content, unknown fixed-object
fields, invalid identities or digests, invalid annotations, duplicate chunk
@@ -67,12 +69,13 @@ annotations, producer identity, and ordered chunks.
## Publication And Compatibility
The map is present only when a chunk plan was accepted and its export is
enabled. It remains publishable if a later lane is rejected, but is absent when
chunk-plan validation rejects the plan. `requested_chunker` identifies the
current pipeline selection, while `producer` identifies the component that
originally produced the accepted plan; they may differ when an accepted plan is
reused.
The map is published when export is enabled, a materialized plan is available,
and the run reaches publication. Payload fields and schema are unchanged.
`requested_chunker` and `producer` describe the current composition; unified
cache entries retain the logical plan, not an earlier run's producer/profile
ledger. Reuse rematerializes against the current source without semantic
reassessment or claims of historical model execution. A strict failure does not
publish a successful bundle merely to expose this auxiliary.
The map contains structure rather than source content: it excludes transcript
bytes, source-unit metadata, chunk text, private model output, reference