Large-record narrative and source-access contract

Large-corpus producers can give an individual record an authored Narrative view and can explicitly control how Explorer presents an external source. Both contracts are additive to okf-explorer-large-corpus.v1.

Record type label

The detail badge uses the first nonblank string in record_type, then type. It preserves the producer's wording and case. If neither field supplies a usable label, Explorer uses the collection's singular record label as before. This applies both to a search summary and to the full record after loading.

For example, a mixed collection can show “Research Protocol” and “Dataset” on individual records. Explorer does not infer a type from a URL or source family, and a type label does not confer authority or review status. Labels are rendered as text, so source markup cannot become executable interface content.

Record narrative

A hydrated record may publish narrative:

{
  "narrative": {
    "title": "Apply within the enclosing process",
    "body": "Repository-authored **Markdown** explaining context and boundaries.",
    "process": { "route": "process/example", "label": "Example process" },
    "previous": [{ "route": "episode/before", "label": "Before" }],
    "next": [{ "route": "episode/after", "label": "After" }],
    "variants": [{ "route": "variant/scotland", "label": "Scotland" }],
    "related": [{ "route": "dataset/related", "label": "Related route" }]
  }
}

body is required when narrative is present. Explorer passes it through its safe Markdown renderer. Route links are optional and use the same governed routes as graph, search and record-locator indexes. When a selected record has this contract, Narrative shows it before any corpus-level reduction summary.

Typed source access

A resource may publish one source_access object:

{
  "source_access": {
    "url": "https://publisher.example/service.xml",
    "label": "Official service response",
    "media_type": "application/xml",
    "display_mode": "xml"
  }
}

All four fields are required. display_mode is one of:

Explorer never executes source markup and applies a 10 MB display limit. A failed browser fetch leaves the official source link available. Source responses are held only in page memory: Explorer does not snapshot, persist or redistribute them.

The record-level source_api_url field remains supported as legacy JSON-only behaviour. It cannot opt an XML, text or HTML response into the inline viewer; producers must publish a typed resource instead.

Bounded references for a selected record

Large bundles may declare an optional record_resources entry point in both the descriptor and data-manifest indexes. Both declarations must bind the same relative JSON path, exact byte length and SHA-256 digest. This is independent of the corpus-wide resource chunks and requires the existing record locator. Older bundles retain their existing resource-index behaviour.

The entry point identifies an okf-record-resource-index.v1 object with the bundle's exact snapshot, algorithm: fnv1a32-prefix-2, and at most 256 buckets. Each bucket has its own byte and digest binding. Its JSON maps an exact record route to an entry such as:

{
  "dataset": "example/one.md",
  "count": 1,
  "chunks": [{
    "path": "references/shared.json",
    "bytes": 512,
    "sha256": "<64 lower-case hexadecimal characters>",
    "rows": [0]
  }]
}

The bucket key is the first byte of the unsigned FNV-1a 32-bit hash of the UTF-8 record route, written as two lower-case hexadecimal characters. Shared chunks contain JSON resource arrays; rows selects only this record's entries. The chunk's complete hash and length are checked before those rows are used. Selected IDs must be unique local identifiers using letters, digits, ., _, ~ or -; each resource must name the resolved record's exact dataset name. A resource's optional route must equal resource/<id>. If the loaded record advertises resource_count, it must match the selected count. Omitting a record with a positive advertised count is an error, not evidence of zero references.

For one record, Explorer accepts at most 16 chunks, 256 selected resources and 2 MiB of shared chunk bytes. A shared chunk may contain at most 1,024 rows. The index is limited to 256 KiB and a bucket to 1 MiB. These files must be uncompressed JSON. Route and shared-chunk caches are finite, and failed loads can be retried without retaining the failed promise. Release-pack transport gzip remains supported for identity JSON members. The logical length must equal the reference's declared length; transport may add at most 64 KiB, and decompression stops at the declared logical length.

Reader and selected-record Resources views load these references without hydrating the whole corpus. Hydrated titles also label native record routes whose kind is not dataset, subject to any declared endpoint-label registry. Reader hash navigation and browser history use the same bounded record and reference loading as the first page load. When this contract is declared, an empty or failed reference load does not activate the legacy source_api_url JSON fallback. Link-only references may state media_type: not-established when no response media type has been evidenced. This is not a downloadable-data or access-rights claim, and Explorer does not fetch those source URLs.

This contract describes presentation, not authority. Producers remain responsible for source identity, assertion provenance, jurisdiction, rights, freshness and limitations.

Further format-specific work

The current contract gives one resource one bounded display mode. Future work tracked under issue #76 should retain, rather than replace, that safe baseline:

A specialist legislation view may reuse a typed XML representation, but its provision tree, legal status and point-in-time interpretation remain a separate domain contract rather than a generic consequence of display_mode: xml.