eric/notarius
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Harmonize foundational integration contracts

Browse Source
This commit is contained in:
Eric Rakestraw
2026-07-26 13:38:55 +00:00
parent fdf8c4afd4
commit 2f506f4985
4 changed files with 252 additions and 338 deletions
Download Patch File Download Diff File Expand all files Collapse all files

128
docs/integrations/chunk-map.md
View File

@@ -1,83 +1,81 @@
# Accepted Chunk Map # Accepted Chunk Map
This document defines the durable accepted chunk-map artifact that the JSON This document defines the optional durable `chunk-map.json` artifact in a
output encoder can write as `chunk-map.json`. It describes the exact accepted, [published JSON bundle](json-output.md). It describes the accepted,
materialized chunks used by a run; it is not a lane artifact and is never an materialized chunk plan used by one run. It is not a lane payload and is never
input to later pipeline steps. Enable it with the JSON output option described an input to a later pipeline step.
in [Configuration](../config.md#json-output-options).
## Identity ## Contract Identity
- Artifact kind: `source/chunk-map` | Property | Value |
- Logical file: `chunk-map.json` | --- | --- |
- Schema ID: `notarius.source.chunk_map` | Artifact kind | `source/chunk-map` |
- Schema name: `notarius_source_chunk_map_v1` | Logical file | `chunk-map.json` |
- Schema version: `v1` | Media type | `application/json` |
- Media type: `application/json` | Schema ID | `notarius.source.chunk_map` |
| Schema name | `notarius_source_chunk_map_v1` |
| Schema version | `v1` |
The checked-in [JSON Schema](../../internal/framework/chunkmap/assets/schemas/source_chunk_map.v1.json) The optional `chunk_map` descriptor in `index.json` identifies this artifact.
defines the strict wire shape. `chunk-map.json` is listed by the optional Export is controlled by the JSON output binding described in
`chunk_map` descriptor in [the JSON output index](json-output.md#indexjson), [Configuration](../config.md#module-bindings-and-validators).
not by the lane-oriented `output_files` collection.
## Payload ## Wire Shape
The payload has these required fields: Every payload has these required fields:
- `source_id`: accepted source-document identity. | Field | Meaning |
- `source_digest`: canonical lower-case `sha256:` digest of that document. | --- | --- |
- `plan_digest`: canonical lower-case `sha256:` digest of the accepted logical | `source_id` | Accepted source-document identity. |
plan. | `source_digest` | Lower-case `sha256:` digest of that source document. |
- `requested_chunker`: chunk module selected by the current resolved pipeline. | `plan_digest` | Lower-case `sha256:` digest of the logical chunk plan. |
- `producer`: the original accepted-plan producer, with required | `requested_chunker` | Chunk module selected by the resolved pipeline. |
`input_module` and `chunk_module`; `llm_profile` is present only for an | `producer` | Original accepted-plan producer. `input_module` and `chunk_module` are required; `llm_profile` is optional. |
LLM-backed producer. | `plan_annotations` | Plan-level annotation namespace map; `{}` when none are present. |
- `plan_annotations`: accepted plan-level annotation namespace map. It is | `chunks` | Non-empty execution-order chunk collection. |
`{}` when no namespaces are present.
- `chunks`: non-empty execution-order collection of accepted chunks.
Each chunk has `id`, zero-based `index`, `source_ref`, positive `unit_count`, Each `chunks` entry contains non-empty `id`, zero-based `index`, `source_ref`,
and an explicit `annotations` namespace map. A source reference has the source positive `unit_count`, and an explicit `annotations` map. `source_ref` contains
ID and inclusive positive `start_unit_id` and `end_unit_id` endpoints. the same `source_id` as the top-level value plus positive inclusive
Annotation values are arbitrary valid JSON under non-empty namespaces. They `start_unit_id` and `end_unit_id` values. Endpoints identify source units; their
are preserved as canonical JSON without interpreting any module-specific numeric values do not by themselves establish source-document order.
namespace.
## Invariants Annotation namespaces are non-empty trimmed strings. Their values are arbitrary
valid JSON and are retained without interpreting a module-specific namespace.
The framework constructs this artifact only after materializing the selected ## Ordering And Validation
logical plan and accepting it through the configured chunk validator chain.
Construction proves the source and plan digests, source-document range order,
materialized chunk IDs and indexes, source references, unit membership and
counts, and plan/range annotations agree exactly. Chunk IDs are unique and
indexes are contiguous and agree with array order.
The codec rejects unknown fixed-object fields, malformed identities or `chunks` are in execution order. Their indexes are contiguous, start at zero,
digests, invalid annotation JSON, trailing JSON content, and any payload whose and equal their array positions; chunk IDs are unique. The emitted map is built
reconstructed logical plan does not reproduce `plan_digest`. It makes only after the selected plan has been accepted and materialized against the
defensive copies at serialization and decoding boundaries. source document, so its ranges, unit counts, annotations, and digests describe
that exact plan.
## Acceptance And Provenance The codec rejects malformed JSON, trailing content, unknown fixed-object
fields, invalid identities or digests, invalid annotations, duplicate chunk
IDs, non-contiguous indexes, and a `plan_digest` that does not match the
reconstructed logical plan. The checked-in
[schema](../../internal/framework/chunkmap/assets/schemas/source_chunk_map.v1.json)
defines the strict JSON shape.
The artifact is available only when the chunk plan was accepted. It remains ## Valid Example
available when a later extraction, merge, or normalization result is rejected;
it is absent when chunk validation rejects the candidate plan.
`requested_chunker` describes the current pipeline selection. `producer` The compact
describes who originally produced the accepted plan. On a cache hit these can [source chunk-map fixture](../../internal/framework/chunkmap/testdata/source_chunk_map.v1.json)
differ: the accepted ranges, annotations, digests, and stable materialized IDs is decoded by the production codec and demonstrates an accepted map with
are reused, while the producer remains the stored producer. Cache paths, annotations, producer identity, and ordered chunks.
actions, references, metadata, warnings, timestamps, and detailed provenance
remain in the run manifest rather than this payload.
## Data Handling ## Publication And Compatibility
The map contains structure, not source content. It excludes transcript bytes, The map is present only when a chunk plan was accepted and its export is
materialized units, source-unit metadata, chunk content, private model enabled. It remains publishable if a later lane is rejected, but is absent when
responses, rejected proposals, debug data, external-reference content, and chunk-plan validation rejects the plan. `requested_chunker` identifies the
filesystem paths. current pipeline selection, while `producer` identifies the component that
originally produced the accepted plan; they may differ when an accepted plan is
reused.
Annotations can nevertheless be source- or model-derived. Treat an enabled The map contains structure rather than source content: it excludes transcript
`chunk-map.json` with the same sensitivity and retention expectations as lane bytes, source-unit metadata, chunk text, private model output, reference
output. Physical placement, confined atomic writing, and permissions follow content, debug data, and filesystem paths. Treat the exported map with the
the ordinary [output operation](../operations.md#output). same care as other published output. Publication location and retention are
defined in [Operations](../operations.md#output-bundles).

98
docs/integrations/dnd-spell-catalog-overlays.md
View File

@@ -1,19 +1,27 @@
# D&D Spell-Catalog Overlay Contract # D&D Spell-Catalog Overlays
This document defines the JSON format accepted by the D&D spell catalog This document defines the optional JSON overlay consumed by the D&D spell
resolver. An overlay supplies campaign-specific spell names and aliases for extractor. An overlay contributes campaign spell names and aliases for
recognition. It does not supply spell rules, levels, classes, effects, or recognition. It does not define spell rules, effects, levels, classes, or
source evidence. transcript evidence. Bind the optional `spell_catalog` reference as described
in [Configuration](../config.md#references-and-ordered-handoffs).
The `dnd/spells` extractor accepts one optional UTF-8 `application/json` overlay ## Contract Identity
bundle through its `spell_catalog` reference slot. The framework materializes
that file relative to the configuration or command-line binding, enforces the
1 MiB slot limit, and records its origin and raw digest separately from the
effective catalog digest.
## Shape | Property | Value |
| --- | --- |
| Consumer | D&D spell extraction and normalization |
| Reference slot | `spell_catalog` |
| Media type | `application/json` |
| Required schema version | `notarius.dnd.spell-catalog-overlay.v1` |
| Base catalog | Embedded D&D 5e 2014 SRD catalog |
An overlay bundle has this shape: At most one overlay document may be bound. The maintained example is
[dnd-spell-catalog.json](../../examples/dnd-spell-catalog.json).
## Wire Shape
This is a minimal valid overlay:
```json ```json
{ {
@@ -22,49 +30,43 @@ An overlay bundle has this shape:
{ {
"id": "campaign.example", "id": "campaign.example",
"ruleset": "dnd-5e-2014", "ruleset": "dnd-5e-2014",
"source": { "source": {"title": "Example campaign spells"},
"title": "Example campaign spells", "spells": [{"name": "Aegis of Emberfall"}]
"version": "1",
"url": "",
"license": ""
},
"spells": [
{
"name": "Aegis of Emberfall",
"aliases": ["Emberfall Aegis"]
}
]
} }
] ]
} }
``` ```
The top-level `schema_version` and `catalogs` fields are required. The schema | Field | Required | Meaning and constraints |
version must be exactly `notarius.dnd.spell-catalog-overlay.v1`, and at least | --- | --- | --- |
one catalog is required. Catalogs require a unique, non-empty, trimmed `id`, | `schema_version` | Yes | Exactly `notarius.dnd.spell-catalog-overlay.v1`. |
the exact `dnd-5e-2014` `ruleset`, a `source`, and a non-empty `spells` array. | `catalogs` | Yes | Non-empty array of catalog objects with unique IDs. |
| `catalogs[].id` | Yes | Non-empty trimmed string. |
| `catalogs[].ruleset` | Yes | Exactly `dnd-5e-2014`. |
| `catalogs[].source.title` | Yes | Non-empty trimmed string. |
| `catalogs[].source.version` | No | String when present. |
| `catalogs[].source.url` | No | String when present. |
| `catalogs[].source.license` | No | String when present. |
| `catalogs[].spells` | Yes | Non-empty array of spell objects. |
| `catalogs[].spells[].name` | Yes | Non-empty trimmed string. |
| `catalogs[].spells[].aliases` | No | Array of non-empty trimmed strings when present. |
`source.title` is required and must be non-empty and trimmed. `source.version`, Unknown fields are rejected at every object level. The document must contain
`source.url`, and `source.license` are optional strings and may be empty. one JSON value; `null` is not accepted for optional strings or aliases.
Each spell requires a non-empty, trimmed `name`. `aliases` may be omitted or
may be an array of trimmed, non-empty strings; JSON `null` is not an alias
array. Overlay objects contain no other supported spell fields.
Decoding is strict: unknown fields, malformed JSON, trailing JSON values, and ## Composition And Compatibility
non-string optional source fields are rejected.
## Composition Notarius starts with the embedded base catalog, then applies overlay catalogs
in ascending catalog-ID order. A new canonical spell name adds a recognition
entry. If an overlay names an existing canonical spell, it augments that spell
with aliases while retaining the established display spelling.
The resolver always starts with the embedded D&D 5e 2014 SRD catalog. Overlay Repeated aliases for the same spell are accepted. A canonical-name, canonical-
catalogs are sorted by `id` before composition, so the input order does not to-alias, or alias-to-alias collision between different spells is rejected,
affect the result. A new canonical name adds a recognition entry. A canonical including a collision with the embedded catalog. Matching uses the catalog’s
name matching an existing canonical name augments that spell and keeps the case, whitespace, and apostrophe normalization, so authors should avoid names
established canonical display spelling. Repeated aliases for the same spell or aliases that normalize to another spell.
are idempotent.
Canonical-name display conflicts and canonical/alias or alias/alias collisions The overlay is a recognition aid only. The durable spell-artifact schema and
between different spells are errors, including collisions with the embedded source-evidence rules are defined by the
catalog. Canonical names and aliases use the catalog's case, whitespace, and [D&D spell artifact contract](dnd-spell-artifacts.md).
common-apostrophe normalization rules. The effective catalog returns canonical
names in sorted order and produces a semantic SHA-256 digest that is stable
under JSON formatting, object-key, catalog, spell, and alias reordering.

254
docs/integrations/json-output.md
View File

@@ -1,201 +1,111 @@
# JSON Output # Published JSON Output
This document is the durable JSON output file-format contract produced by the This document defines the logical JSON bundle emitted by the production JSON
production JSON encoder and written by the CLI. Selectable output-encoder keys output encoder. The bundle’s physical destination, atomic publication, and
are cataloged in retention are operational concerns; see [Operations](../operations.md#output-bundles).
[Configuration](../config.md#implemented-production-modules). Output configuration, including chunk-map export, belongs in
[Configuration](../config.md#module-bindings-and-validators).
The output module produces the logical bundle described here. The CLI's ## Bundle Layout
physical placement and lifecycle for that bundle are defined in
[Operations](../operations.md#output-directory).
## Files All paths below are logical, relative, slash-separated bundle paths. The
encoder always emits the first four JSON files below and adds lane or chunk-map
files when their corresponding artifacts are available:
The encoder writes: | Path | Purpose |
| --- | --- |
| `index.json` | Entry point that names the other published files and lane payloads. |
| `manifest.json` | Run provenance and result summaries. |
| `rejected.json` | Rejected pipeline outputs. |
| `warnings.json` | Accepted-output and run warnings. |
| `lanes/<safe-lane-id>.json` | One normalized artifact payload for each lane. |
| `chunk-map.json` | Optional accepted chunk map, when its export is enabled and available. |
- `index.json` JSON files are pretty-printed with a trailing newline. Lane payloads are
- `manifest.json` accepted only when their media type is `application/json`.
- `lanes/<lane-id>.json`, one file per normalized serialized artifact
- `rejected.json`
- `warnings.json`
- `chunk-map.json`, only when the JSON output binding enables
`include_chunk_map` and the run has an accepted chunk map
Files are pretty-printed JSON with a trailing newline when the payload is JSON.
Logical file paths are relative, slash-separated, and may not contain `..`.
## `index.json` ## `index.json`
Shape: `index.json` is the bundle’s discovery document. An approved run with no
normalized lanes has this valid minimal index:
```json ```json
{ {
"manifest_file": "manifest.json", "manifest_file": "manifest.json",
"output_files": [ "output_files": [],
{
"lane_id": "spells",
"media_type": "application/json",
"file": "lanes/spells.json",
"module_key": "noop",
"schema_id": "notarius.dnd.spells",
"schema_name": "notarius_dnd_spells_v1",
"schema_version": "v1"
}
],
"rejected_file": "rejected.json", "rejected_file": "rejected.json",
"warnings_file": "warnings.json" "warnings_file": "warnings.json"
} }
``` ```
`output_files` is sorted by lane ID. Output file names are produced by | Field | Required | Meaning |
sanitizing the lane ID: | --- | --- | --- |
| `manifest_file` | Yes | Always `manifest.json`. |
| `output_files` | Yes | Lane descriptors sorted by `lane_id`. |
| `rejected_file` | Yes | Always `rejected.json`. |
| `warnings_file` | Yes | Always `warnings.json`. |
| `chunk_map` | No | Descriptor for the pipeline-wide `chunk-map.json`; never a lane descriptor. |
- characters outside `A-Z`, `a-z`, `0-9`, `.`, `_`, and `-` become `_`; Each lane descriptor has required `lane_id` and `file`. It may also include
- repeated `..` sequences are replaced; `media_type`, `module_key`, `schema_id`, `schema_name`, and `schema_version`
- leading and trailing `.`, `_`, and `-` are trimmed; when supplied by the normalized artifact. A `chunk_map` descriptor contains
- empty sanitized names are rejected;
- two lanes that sanitize to the same output file are rejected.
`manifest_file`, `rejected_file`, and `warnings_file` contain the fixed paths
shown above. Each `output_files` entry requires `lane_id` and `file`. It also
contains the normalized payload `media_type`, normalizer `module_key`, and
response `schema_id`, `schema_name`, and `schema_version` when those values are
available.
When present, the top-level optional `chunk_map` descriptor contains exactly
`artifact_kind`, `file`, `media_type`, `schema_id`, `schema_name`, and `artifact_kind`, `file`, `media_type`, `schema_id`, `schema_name`, and
`schema_version`. It identifies the pipeline-wide `chunk-map.json`; it is not `schema_version`; its payload is defined by the
a lane output and never appears in `output_files`. The descriptor and file are [Accepted Chunk Map contract](chunk-map.md).
both absent when export is disabled or no chunk plan was accepted. Its payload
contract is defined by [Accepted Chunk Map](chunk-map.md). The lane path is derived from its lane ID. Characters outside letters, digits,
periods, underscores, and hyphens become underscores; `..` sequences are
neutralized; leading and trailing periods and underscores are removed. A lane
that produces an empty name, or two lanes that produce the same path, makes
output encoding fail.
## Lane Payloads
Each `lanes/<safe-lane-id>.json` file is the codec-owned normalized JSON for
that lane. Consumers should use the index descriptor’s schema identity rather
than infer a lane schema from its name. The current D&D payload contracts are
[spells](dnd-spell-artifacts.md), [NPCs](dnd-npc-artifacts.md),
[NPC interactions](dnd-npc-interaction-artifacts.md),
[combat turns](dnd-combat-turn-artifacts.md),
[item events](dnd-item-event-artifacts.md), and
[scene descriptions](dnd-scene-description-artifacts.md).
## `manifest.json` ## `manifest.json`
`manifest.json` contains a run manifest. This abridged example shows its core `manifest.json` is published provenance, not a copy of lane payloads or a
structure: checkpoint store. Fields without a value may be omitted. Its top-level fields
group into the following externally observable summaries:
```json | Group | Fields |
{ | --- | --- |
"run_id": "run-123", | Run identity and result | `run_id`, `pipeline_id`, `pipeline_digest`, `schema_version`, `validation_status`, `started_at`, `completed_at` |
"pipeline_id": "dnd-session", | Resolved components | `input_module`, `chunker`, `extractors`, `merger`, `normalizer`, `output_encoder`, `artifact_lanes`, `validator_chains`, `module_metadata` |
"artifact_lanes": [ | Source and references | `source_digests`, `references` |
{ | Published result summaries | `normalized_outputs`, `rejected_outputs` |
"id": "spells", | Execution summaries | `chunk_plan`, `checkpoint_decisions`, `llm_profiles`, `metadata` |
"extractor": "dnd/spells",
"merger": "appendorder",
"normalizer": "noop"
}
],
"validation_status": "approved",
"started_at": "2026-01-01T00:00:00Z",
"completed_at": "2026-01-01T00:00:01Z"
}
```
Fields with empty values may be omitted by JSON encoding. `references` records provenance such as the target, slot, origin, digest,
media type, size, and generated-artifact identity. It does not contain
reference content. `normalized_outputs` and `rejected_outputs` likewise
summarize results without embedding lane payload bytes. A chunk-plan summary is
provenance for the plan used by this run; cache records, debug artifacts, and
other operational state are not published as bundle files.
The manifest fields are: ## Rejections And Warnings
- `run_id`, `pipeline_id`, and `pipeline_digest`: run and resolved-pipeline `rejected.json` is always an object with a `rejected` array. Each entry has
identity; required `stage` and `message`; `step_id`, `lane_id`, `module_key`, `chunk_id`,
- `input_module`, `chunker`, `extractors`, `merger`, `normalizer`, and `chunk_index`, `validator_name`, `reason_code`, `attempt_count`, and
`output_encoder`: resolved module keys; `diagnostic_artifact_path` are present only when applicable.
- `chunk_plan`: payload-free provenance for the effective chunk plan. `mode`
is the effective cache mode; `action` is `reused`, `generated`,
`refreshed`, or `bypassed` when a plan was materialized. `requested_module`
is the current pipeline chunker, while `producer_input_module`,
`producer_module`, `producer_llm_profile`, `producer_references`,
`producer_metadata`, `source_digest`, `plan_digest`, `plan_schema_version`,
and `created_at` describe the stored or generated producer when available.
A cached plan can therefore identify a producer different from the requested
module. This object never embeds ranges, units, annotations, prompts,
responses, or reference content;
- `module_metadata` and `artifact_lanes`: module and per-lane provenance,
including prompt and response-schema provenance when provided;
- `validator_chains`: resolved validation points and validators;
- `source_digests` and `references`: source and reference provenance;
- `normalized_outputs` and `rejected_outputs`: payload-free result summaries;
- `llm_profiles`: selected profile IDs and provider or model names when
available;
- `metadata`: the effective prompt `session_id`;
- `validation_status`: `approved` or `rejected`;
- `started_at` and `completed_at`: UTC run timestamps.
`source_digests` contains source document digests only. Bound references are `warnings.json` is always an object with a `warnings` array. Each warning has
recorded separately under `references`, which contains provenance only: target `reason_code` and `message`; `scope` is optional. Both arrays are empty when
stage, lane ID when present, slot name, origin type and URI, digest, media there is nothing to report.
type, byte size, and binding source. Reference content is not written to
durable output.
Reference `stage` is `chunk`, `extract`, `merge`, or `normalize`. `lane_id` is ## Compatibility
omitted for chunk references and present for extract, merge, and normalize
references.
`validation_status` is `approved` when no outputs were rejected and `rejected` The index is the authoritative map from a logical lane to its published
when one or more outputs were rejected. payload. Consumers must tolerate omitted optional manifest and descriptor
fields, and should rely on the linked artifact contract for each lane’s JSON
Producer warnings and the current run's chunk-validation warnings remain in shape. This contract describes the published logical bundle only; it does not
`warnings.json`. The manifest records only provenance and decision summaries; promise a filesystem layout or expose internal state formats.
empty producer-only values are omitted for compatibility with existing readers.
`validator_chains` records the resolved validator chain for each validation
point. Entries include stage, lane ID when applicable, module key, and validators
with key and execution class. Empty chains are recorded with an empty
`validators` array, including chains resolved from explicit empty config
overrides.
`normalized_outputs` summarizes each normalized lane output without embedding
payload bytes. Entries include lane ID, normalizer module key, source ID, media
type, and response schema provenance where available.
`rejected_outputs` summarizes rejected module outputs without embedding raw
payload bytes. Entries include stage, lane, module, chunk, validator or reason,
message, attempt count, and optional diagnostic artifact path.
## Output Payload Files
Each normalized serialized artifact is written to
`lanes/<sanitized-lane-id>.json`. The JSON output encoder is domain-neutral and
accepts only artifacts whose codec media type is `application/json`. The file
contains the codec-owned JSON bytes pretty-printed.
The schema of each lane payload is owned by that artifact contract. For the
current D&D lanes, see [D&D Spell Artifact](dnd-spell-artifacts.md),
[D&D NPC Artifact](dnd-npc-artifacts.md), and
[D&D Combat-Turn Artifact](dnd-combat-turn-artifacts.md), and
[D&D Scene Description Artifact](dnd-scene-description-artifacts.md).
## `rejected.json`
Shape:
```json
{
"rejected": []
}
```
When output validation rejects an output, each entry contains `stage` and
`message`. It includes `lane_id`, `module_key`, `chunk_id`, `chunk_index`,
`validator_name`, `reason_code`, `attempt_count`, and
`diagnostic_artifact_path` when applicable.
## `warnings.json`
Shape:
```json
{
"warnings": [
{
"scope": "extract",
"reason_code": "example",
"message": "human-readable warning"
}
]
}
```
`warnings` is an empty array when no warnings are reported.
Each warning requires `reason_code` and `message`; `scope` is omitted when it is
empty.

110
docs/integrations/seriatim.md
View File

@@ -1,69 +1,73 @@
# Seriatim Transcript JSON # Seriatim Transcript Input
This document is the external input contract consumed by the production This document defines the JSON transcript accepted by the production Seriatim
Seriatim input adapter. Selectable input-adapter keys are cataloged in input adapter. It is a source input, not a durable lane artifact. Configure the
[Configuration](../config.md#implemented-production-modules). input adapter through [Configuration](../config.md#production-module-keys).
## Adapter ## Contract Identity
- Source format: `application/vnd.seriatim+json` | Property | Value |
| --- | --- |
| Consumer | Seriatim input adapter |
| Media type | `application/vnd.seriatim+json` |
| Source document kind | `transcript` |
| Source-unit kind | `transcript_segment` |
## Accepted Shape ## Accepted Shape
The input must be one JSON object with top-level `metadata` and `segments` The input is one JSON object containing `metadata` and a non-empty `segments`
fields. This covers the maintained minimal fixture and Seriatim intermediate array. This minimal document is valid:
output that provides the same required segment fields.
The maintained example is ```json
[examples/seriatim-minimal-transcript.json](../../examples/seriatim-minimal-transcript.json). {
"metadata": {"id": "session-alpha"},
"segments": [
{
"id": 1,
"start": 0,
"end": 4,
"speaker": "Aria",
"text": "Aria casts Cure Wounds."
}
]
}
```
Required top-level fields: The maintained two-segment input is
[seriatim-minimal-transcript.json](../../examples/seriatim-minimal-transcript.json).
- `metadata`: an object. Its entries are accepted as source metadata. | Field | Required | Meaning and constraints |
- `segments`: a non-empty array of segment objects. | --- | --- | --- |
| `metadata` | Yes | JSON object. Its entries become source metadata; no particular metadata key is otherwise required. |
| `segments` | Yes | Non-empty array of segment objects, kept in input order. |
| `segments[].id` | Yes | Positive canonical decimal integer, supplied as a JSON number or string. IDs must be unique. |
| `segments[].start` | Yes | Finite, non-negative numeric value, supplied as a JSON number or string. |
| `segments[].end` | Yes | Finite, non-negative numeric value that is not earlier than `start`. |
| `segments[].speaker` | Yes | String that is non-empty after trimming. |
| `segments[].text` | Yes | String that is non-empty after trimming. Its original text is retained. |
Required segment fields: Additional top-level and segment fields are ignored. A missing required field,
`null` in place of an object or array, malformed JSON, or more than one
top-level JSON value is rejected.
- `id`: a positive integer JSON number or canonical decimal string without ## Source Identity And References
leading zeros or surrounding whitespace;
- `start`: a finite, non-negative JSON number or numeric string;
- `end`: a finite, non-negative JSON number or numeric string that is not less
than `start`;
- `speaker`: a non-empty string;
- `text`: a non-empty string.
Other top-level and segment fields, such as `categories`, are ignored. The adapter chooses the source ID in this order:
Multiple top-level JSON values are rejected. 1. a non-empty source ID supplied by the calling request;
2. non-empty string `metadata.id`;
3. non-empty string `metadata.source_id`;
4. `seriatim:` followed by the first 16 hexadecimal characters of the raw
input’s SHA-256 digest.
## Validation Each accepted segment becomes one source unit whose unit ID is `segments[].id`.
Its self-reference uses the derived source ID and the same segment ID for both
range endpoints. Artifact contracts use those segment IDs when they cite
transcript evidence.
The adapter rejects empty input, malformed JSON, multiple top-level JSON values, ## Compatibility
non-object segment values, duplicate segment IDs, and any violation of the
shape or field constraints above.
Segment text is preserved as provided, but it must not be empty after trimming. This adapter accepts only the shape described here. A broader Seriatim export
is usable only when it supplies this object, metadata, and segment shape with
## Derived Identity the stated types and constraints. Unknown additional fields do not add
Notarius behavior.
Notarius identifies the parsed source in this order:
1. `metadata.id`, when it is a non-empty string after trimming;
2. `metadata.source_id`, when it is a non-empty string after trimming;
3. `seriatim:<first-16-hex-chars-of-raw-sha256>`.
The exact raw input SHA-256 remains the basis of the fallback source ID. The
source digest recorded in output provenance is instead the SHA-256 of the
canonical generic source document, excluding the digest field itself. It covers
the derived source identity, document kind and format, ordered units and their
self-references, and accepted metadata. Segment IDs become the unit IDs used by
artifact source references; each produced unit carries a self-reference whose
source ID is the derived document ID and whose start and end IDs both equal the
segment ID.
## Compatibility Limit
This contract covers only Seriatim transcript JSON with the top-level
`metadata` object and `segments` array described here. Broader Seriatim output
schemas are compatible only when they provide these required fields with the
accepted types.