Structured-markdown profile v1

Audience: on-prem/air-gap RAG integrators, sovereign-cloud teams, defence and regulated-sector engineers who ingest documents into a chunked, auditable index inside their own perimeter. This page is the wire contract: every key, why it exists for that audience, and what it does and does not promise. It is a reference for anything consuming @awacloud/oconv's output, not just for @awacloud/oconv itself.

Prerequisites. Producing a profile-v1 document takes oconv.toMd from the @awacloud/oconv main entry (registered on an @awacloud/fw ModuleRuntime — see the package README's Quick Start), in a browser or on the runtimes the package's engines field names (Bun ≥ 1.0, Node ≥ 20); oconv.fromMd accepts one back as input. Consuming one needs no oconv code at all: any YAML reader plus any CommonMark/GFM parser reads it.

A profile-v1 document is a literal YAML front-matter block followed by a CommonMark/GFM body:

---
profile: v1
ir: oconv-ir/v1
sourceFormat: docx
sourceName: report.docx
sourceBytes: 1556
sourceSha256: 7be541047cdb2255188fdf68ed6ddc98c47ed22332093df494dcb3f5c7f60b7c
convertedAt: 2026-07-20T00:00:00Z
converter: oconv
converterVersion: 1.0.0
engine: bun
blocks: 6
anchors:
  - { level: 1, anchor: sovereign-rag-ingestion }
  - { level: 2, anchor: why-air-gap-matters }
  - { level: 3, anchor: chunking }
lossy: true
losses:
  - { code: block/dropped, detail: footnote }
assets:
  - { kind: image, name: logo.png }
---

Every line through the anchors: list is what toMd emits for the package's own docx-smoke.docx corpus fixture, called with that convertedAt and engine: 'bun'. The losses: and assets: entries are added to show every key: that fixture converts with an empty ledger and no image, so its real front matter ends at lossy: false.

Every front-matter key below is emitted exactly in this order by src/write/ir-to-md.js (oconvIrToMd); anchors:, losses: and assets: are each omitted entirely when empty (never an empty []).

Key-by-key semantics

Determinism and auditability

Two properties matter for a sovereign/air-gap offer, and both are structural (not best-effort):

1. sourceSha256 pins the input. A reviewer with the original file can recompute the hash and confirm the front matter describes THAT exact byte sequence.
2. convertedAt is always caller-injected — never defaulted to Date.now(). src/oconv.js's toMd throws oconv: convertedAt is required when omitted. Consequence, verified by the fidelity harness: converting the same bytes twice with the same convertedAt produces byte-identical markdown, and changing only convertedAt changes exactly that one front-matter line — nothing else in the document shifts. This is the property an audit trail needs: a re-run is a diff, not a fresh unknown.

This determinism claim is scoped to the to-md direction, with two from-md exceptions: the .docx and .pdf targets. The .docx target of fromMd is byte-reproducible: @awacloud/ooxml stamps every zip entry with a fixed 1980-01-01 00:00 timestamp, so two identical fromMd(..., 'docx') calls on the same markdown produce byte-identical output — tests/roundtrip.integration.test.js § "reproducibility — md -> docx is byte-reproducible". The .odt target is not: the ODF package writer stamps the current time, so two identical calls give equal document models but may give different bytes; see docs/loss-matrix.md "From-md reproducibility" for the full statement. The .pdf target IS byte-reproducible: irToPdf never stamps a date or an /ID, so two identical fromMd(..., 'pdf') calls on the same markdown produce byte-identical output — tests/roundtrip.integration.test.js § "reproducibility — md -> pdf is byte-reproducible".

Chunking usage

anchors: is the section index a RAG ingestion pipeline chunks against: split the body on #/##/… headings, and address each chunk by its #anchor slug. Slugs are deterministic and ASCII-only by construction (NFKD → strip combining marks → lowercase → [^a-z0-9]+ → -, with a -1, -2 … collision suffix for duplicate headings) — safe for any downstream index, URL, or filename. anchors.length equals the number of #-heading lines the writer emits for real headings (headings inside a GFM table cell are excluded on both sides — a cell renders inline-only, so such a heading never becomes a #-line and is correctly un-indexed), but this is not an absolute count of #-prefixed lines in the body: a fenced code block can carry #-lines of its own. A source paragraph line that itself begins with a literal # (e.g. # Ligne FACT) is escaped by @awacloud/md's Markdown renderer (\# Ligne FACT; likewise a line-leading 1., 1), -, +, * or >), so it re-parses as paragraph text, never as a heading. Measured on facturx-minimum-sample.pdf: its body used to carry 5 #-prefixed lines against 0 headings; it now carries 0 against 0, and tests/fidelity.integration.test.js includes that fixture in the heading-count/anchor-count equality assertion again.

Profile v1 as INPUT (fromMd)

fromMd accepts a profile-v1 document — or plain CommonMark/GFM with no front matter at all — and writes a .docx, .odt or .pdf container. The relationship with this profile is read-only and one-directional: a leading front-matter fence (---/+++/;;;, detected the same way @awacloud/md's mdFrontmatter.stripFrontmatter detects it on the toMd side) is stripped before parsing (src/read/md-to-ir.js, composing mdFrontmatter.stripFrontmatter from @awacloud/md/extra/frontmatter.js — never an @awacloud/md internal), and:

• it is never parsed — no YAML/TOML/JSON decoding of its content, by design (same "emit, never parse" stance the reader takes for the stripped block on the toMd write side, generalized to the read direction too);
• it is recorded as a loss, not a silent strip — one {code: 'frontmatter/stripped', detail: <lang>} entry per document (lang is 'yaml' | 'toml' | 'json', matching the fence syntax), verified by src/read/md-to-ir.test.js for all three fence kinds and by tests/roundtrip.integration.test.js for a real toMd-produced profile document fed back in (sourceSha256/converterVersion and all) — a deliberate design decision, not a gap;
• it is never written into the target container — no .docx/.odt core-properties or custom-metadata part is populated from it. The target container's own fixed provenance is unrelated to it: none for docx, meta:generator: '@awacloud/odf' for odt, /Producer + /Creator '@awacloud/oconv' for pdf (see convert.md). tests/roundtrip.integration. test.js's profile-v1 input leg confirms the front-matter text is absent from the produced docx body via docxApi.toText(docxApi.read(bytes) .document).

In short: a profile-v1 document's front matter describes a prior conversion (the toMd call that produced it) — it is provenance about the PAST, not an instruction for the container fromMd is about to build, and it does not round-trip. A document produced by fromMd carries no sourceSha256/convertedAt/losses front matter of its own; if a caller wants an audit trail for the from-md direction, it is their own responsibility to keep one, @awacloud/oconv emits none.

Loss ledger — codes in use

Losses are data, appended to losses: in document order (reader losses lead, writer losses follow) — never a side-channel log line. A detected loss is always recorded; a construct the pipeline cannot detect is not (the loss matrix lists the known silent cases). detail is a string on every reader code and on the fromMd reader and docx/odt writer codes below; the .pdf typesetter's layout/*, text/unencodable and inline/* codes carry an object detail instead, and the per-block records among them also name the block's index and kind beside code. The fromMd and convert facades return those records unchanged, and so does the worker reply. Codes emitted by the seven shipped readers and the md writer:

Read-side resolution scope for the two odt *-unresolved codes: semantic resolution covers content.xml automatic styles AND styles.xml office:styles styles that are fully mapped (a single style, no style:parent-style-name chain); monospace resolves only through a declared fixed-pitch or generic-modern font face. Foreign documents styled through parent chains or partially-mapped styles still yield run/format-unresolved / list/numbering-unresolved on read — that is why these two codes survive the tier-2 raise rather than being retired with the four write-side codes below.

Remaining reader codes:

xobject/form-dropped, xobject/form-cycle, xobject/form-depth, xobject/form-budget, content/undecodable, text/font-unresolved and text/width-approximated are each pinned by a dedicated producing test, src/read/pdf/text-extract.test.js.

Codes emitted by the fromMd reader (src/read/md-to-ir.js) and the three fromMd writers (src/write/ir-to-docx.js, src/write/ir-to-odt.js, and src/write/ir-to-pdf.js + its src/write/pdf/* typesetting-layer modules):

The .pdf target's bounded typesetter (src/write/ir-to-pdf.js + src/write/pdf/*) emits its own vocabulary — 10 layout/* codes, text/unencodable and 2 inline/* codes — the full options/font-route context for each lives in docs/pdf-writer.md; this table states only the vocabulary:

Retired codes (odt target)

Four (odt target only) codes shipped in earlier ledgers and are retired: @awacloud/odf gained a typed semantic write model, so src/write/ir-to-odt.js now writes every construct they used to record as lost, and md→odt reaches tier 2. They are listed here — not silently deleted — because documents converted before the retirement carry them in their losses: front matter, and a consumer reading an archived profile-v1 document must still be able to look them up.

Proof of retirement: src/write/ir-to-odt.test.js § "exhaustive absence of the four retired loss codes", and tests/roundtrip.integration.test.js leg 4 (md-structural.md → odt with an EMPTY ledger).

Retired code (docx target)

run/code-degraded shipped in earlier ledgers and is retired: @awacloud/ooxml round-trips rPr.font through <w:rFonts> (ooxml/src/docx/properties.js), so src/write/ir-to-docx.js now writes font: 'Courier New' for a code run and src/read/docx-to-ir.js reads it back via a frozen monospace name allowlist — md → docx → md keeps inline code as backticks. Listed here — not silently deleted — because documents converted before the retirement carry the code in their losses: front matter.

Proof of retirement: src/write/ir-to-docx.test.js § "exhaustive absence of run/code-degraded", and tests/roundtrip.integration.test.js leg 1 (md-structural.md → docx → md, empty fromMd ledger, backticks recovered).

The full preserved/degraded/dropped picture per pair is docs/loss-matrix.md — this table is the vocabulary, that page is the coverage claim.

Zero network, zero external tooling

Nothing in the reader → pivot IR → writer path performs I/O, touches the network, or shells out to an external tool. The Web APIs used beyond plain ES are crypto.subtle.digest (source hashing, toMd only) and performance.now() (call-duration timing — src/oconv.js, src/worker.js) — available in a browser tab, in Bun, and inside a Worker alike. This is a hard property for an air-gapped deployment, not a soft goal: bun test packages/front/office/oconv/ runs the whole suite, including the fidelity harness, with no network access.

Versioning

profile and ir are independent keys on purpose: the wire profile can stay v1 across pivot IR revisions (oconv-ir/v1 → v2 → …) as long as the front-matter/body contract itself does not change; a profile-breaking change gets its own profile: v2.

See also

• docs/loss-matrix.md — per-pair fidelity coverage.
• ../README.md — package overview, Quick Start, worker usage.
• src/write/ir-to-md.js — the writer this page documents (its own file-header JSDoc is the profile's original, code-adjacent spec).