Spec Studio

The Markdown envelope is explicit and bounded

spec:carrier.envelope-contractContract · featureready floor ready

Packs: pack:self-hosting-v1

Design: no design entries · no pinned declarations · 1 decision

Findings: no errors, no warnings

specs/carrier/envelope-contract.sdp.md

No open questions and no blocking questions; implementation binding present, verifier binding present, and expected-outcome oracle none.

Intent
outcome
Make a Markdown Spec's identity and descriptors deterministic to reify.
Contract
rule line 20 · specs/carrier/envelope-contract.sdp.md:20
A Markdown Spec declares id, kind, altitude, readiness, and relations in bounded YAML frontmatter; its first H1 declares title.
rule line 21 · specs/carrier/envelope-contract.sdp.md:21
The envelope key set is closed and every one of its five keys is required: a key outside the set is refused rather than absorbed, and a missing key refuses the document rather than being defaulted.
rule line 22 · specs/carrier/envelope-contract.sdp.md:22
Each relation type takes one target or a list; its target forms follow spec:model.relation-reasons, and an example's declared verifies may carry exercises under spec:model.rule-keys.
rule line 23 · specs/carrier/envelope-contract.sdp.md:23
relations: {} is written explicitly when the logical relation set is empty — honest carrier syntax, not a new logical requirement: the physical key catches a truncated envelope at reification while the model itself stays relation-optional.
rule line 24 · specs/carrier/envelope-contract.sdp.md:24
A derived name is never authorable in the envelope: a delivery-fact or graph-field key (implemented, has-verifier, hasVerifier, observed, claim, deliveryFacts, nodeType, specKind, satisfies, verifies, belongsTo or models) is refused as extract/reserved-property, because delivery facts are derived and never authored; title is refused as extract/invalid-frontmatter, and any other unknown envelope key as extract/unrecognized-property.
rule line 25 · specs/carrier/envelope-contract.sdp.md:25
The Protocol owns the envelope grammar and the parser policy while the pinned YAML library stays a swappable representation behind that contract, so an unsupported YAML construct is refused within explicit byte bounds on the carrier and its frontmatter rather than silently becoming carrier semantics.
rule line 26 · specs/carrier/envelope-contract.sdp.md:26
The bounds are 256 KiB per carrier, 32 KiB of frontmatter, 16 KiB per scalar, 2,000 YAML nodes, and a nesting depth of 16; YAML anchor (&name) and alias (*name) syntax and explicit YAML tags (!tag) are refused at any size.
rule line 27 · specs/carrier/envelope-contract.sdp.md:27
The frontmatter opens at byte zero with an exact --- line and closes at the next exact --- line; a byte-order mark, a ... line in the frontmatter, a further exact --- line in the body, a lone CR, or mixed LF and CRLF newlines refuses the carrier.

8 unkeyed rules.

Verification

Verifier bindings

  • test:protocol.envelope-contract · frontmatter contract tests verify the Markdown envelope · anchored · test anchor binding present · test/markdown-reifier.test.ts:97

    External run evidence from test/markdown-reifier.test.ts

    Test anchors: test:protocol.envelope-contract, test:protocol.markdown-parser, test:protocol.prose-ownership. Specs verified by those bindings: spec:carrier.envelope-contract, spec:carrier.markdown-parser, spec:carrier.prose-ownership-rule.

    Run 1: external run evidence from vitest 4.1.10

    Build: CI 380 · Branch: feature/roadmap-and-slices-v0 · Commit: 34909918bf0be0e849959644401797191cae379f · Start: 2026-10-22T17:40:31.456Z · Stop: 2026-10-22T17:42:16.171Z

    NameSuiteResultDuration
    reifies a lawful Markdown Pack manifestMarkdown frontmatter reifierpassed7.35 ms
    refuses a Spec-only key on a PackMarkdown frontmatter reifierpassed1.84 ms
    refuses Pack membership on a SpecMarkdown frontmatter reifierpassed2.34 ms
    refuses a Pack section headingMarkdown frontmatter reifierpassed1.36 ms
    refuses a wrong-namespace Pack memberMarkdown frontmatter reifierpassed1.02 ms
    refuses a reserved derived-name key on a PackMarkdown frontmatter reifierpassed0.85 ms
    refuses a pack: id that fails the id grammarMarkdown frontmatter reifierpassed1.02 ms
    reifies the frozen corpus envelopes at their id token linesMarkdown frontmatter reifierpassed15.53 ms
    maps scalar and list relations in authored orderMarkdown frontmatter reifierpassed1.91 ms
    distinguishes an explicit empty relation set from a missing relation keyMarkdown frontmatter reifierpassed1.34 ms
    refuses warning without throwingMarkdown frontmatter reifierpassed1.25 ms
    refuses directive without throwingMarkdown frontmatter reifierpassed1.04 ms
    refuses tag without throwingMarkdown frontmatter reifierpassed1 ms
    refuses anchor without throwingMarkdown frontmatter reifierpassed0.83 ms
    refuses alias without throwingMarkdown frontmatter reifierpassed0.86 ms
    refuses merge without throwingMarkdown frontmatter reifierpassed0.91 ms
    refuses complex key without throwingMarkdown frontmatter reifierpassed0.99 ms
    refuses non-string scalar without throwingMarkdown frontmatter reifierpassed0.59 ms
    refuses body delimiter without throwingMarkdown frontmatter reifierpassed0.2 ms
    caps findings and leaves a healthy sibling independently reifiableMarkdown frontmatter reifierpassed19.8 ms
    caps body findings with the frozen structure finding IDMarkdown frontmatter reifierpassed1.45 ms
    reports a genuine YAML document warningMarkdown frontmatter reifierpassed0.99 ms
    contains the YAML parser's unknown throw at the public reifier boundaryMarkdown frontmatter reifierpassed19.86 ms
    enforces the 256 KiB carrier byte limit at and immediately over its boundaryMarkdown frontmatter reifierpassed1.98 ms
    enforces the 32 KiB frontmatter byte limit at and immediately over its boundaryMarkdown frontmatter reifierpassed1.09 ms
    enforces the 16 KiB scalar byte limit at and immediately over its boundaryMarkdown frontmatter reifierpassed2.21 ms
    enforces the 2,000 node limit at and immediately over its boundaryMarkdown frontmatter reifierpassed651.75 ms
    enforces the depth limit of 16 at and immediately over its boundaryMarkdown frontmatter reifierpassed1.5 ms
    refuses duplicate relation keysMarkdown frontmatter reifierpassed0.56 ms
    refuses duplicate targets within one relation listMarkdown frontmatter reifierpassed0.4 ms
    refuses an empty relation sequenceMarkdown frontmatter reifierpassed6.52 ms
    refuses a wrong-namespace relation targetMarkdown frontmatter reifierpassed0.47 ms
    refuses an entry address in the Spec id at the field's lineMarkdown frontmatter reifierpassed0.67 ms
    refuses an entry address in a relation target at the field's lineMarkdown frontmatter reifierpassed0.41 ms
    refuses an entry address in a Pack member at the field's lineMarkdown frontmatter reifierpassed0.39 ms
    refuses an entry address in a Pack model reference at the field's lineMarkdown frontmatter reifierpassed4.11 ms
    refuses a Pack whose own id carries an entry address with the namespace reasonMarkdown frontmatter reifierpassed0.46 ms
    accepts distinct relation keys that share a targetMarkdown frontmatter reifierpassed0.51 ms
    accepts a pure CRLF carrierMarkdown frontmatter reifierpassed0.62 ms
    refuses a byte-order markMarkdown frontmatter reifierpassed0.14 ms
    refuses an indented openerMarkdown frontmatter reifierpassed0.1 ms
    refuses a document-end closerMarkdown frontmatter reifierpassed0.08 ms
    refuses a lone CR after a valid LF carrierMarkdown frontmatter reifierpassed0.06 ms
    refuses mixed CRLF and LF newlinesMarkdown frontmatter reifierpassed0.06 ms
    maps the ruled title, intent, and behavior lists from the bodyMarkdown frontmatter reifierpassed4.99 ms
    maps the ruled fences and every remaining typed ownerMarkdown frontmatter reifierpassed2.46 ms
    serializes owned prose canonically across both public carrier reifiersMarkdown frontmatter reifierpassed32.16 ms
    serializes GWT and behavior key permutations to identical bytesMarkdown frontmatter reifierpassed11.66 ms
    omits absent prose fields and rejects constraint-local prose from the TypeScript carrierMarkdown frontmatter reifierpassed6.96 ms
    uses the first minimum heading suggestion within edit distance twoMarkdown frontmatter reifierpassed1.16 ms
    refuses a missing H1 through the frozen body diagnosticMarkdown frontmatter reifierpassed0.48 ms
    refuses an empty H1 through the frozen body diagnosticMarkdown frontmatter reifierpassed0.35 ms
    refuses a heading beyond suggestion distance two through the frozen body diagnosticMarkdown frontmatter reifierpassed0.59 ms
    refuses a tied heading using the first minimum through the frozen body diagnosticMarkdown frontmatter reifierpassed0.67 ms
    refuses a blank line in a fence through the frozen body diagnosticMarkdown frontmatter reifierpassed2.67 ms
    refuses fence attributes through the frozen body diagnosticMarkdown frontmatter reifierpassed0.5 ms
    refuses an unclosed fence through the frozen body diagnosticMarkdown frontmatter reifierpassed0.43 ms
    refuses a gwt fence on a non-example through the frozen body diagnosticMarkdown frontmatter reifierpassed0.43 ms
    refuses an invalid Verification mode through the frozen body diagnosticMarkdown frontmatter reifierpassed1.44 ms
    refuses a repeated identical literal heading through the frozen body diagnosticMarkdown frontmatter reifierpassed0.42 ms
    refuses ordered dot list in narrativeMarkdown frontmatter reifierpassed0.43 ms
    refuses ordered parenthesis list in narrativeMarkdown frontmatter reifierpassed0.25 ms
    refuses star list in narrativeMarkdown frontmatter reifierpassed0.31 ms
    refuses plus list in narrativeMarkdown frontmatter reifierpassed3.47 ms
    refuses ordered dot tab list in narrativeMarkdown frontmatter reifierpassed0.44 ms
    refuses ordered parenthesis tab list in narrativeMarkdown frontmatter reifierpassed0.37 ms
    refuses star tab list in narrativeMarkdown frontmatter reifierpassed0.58 ms
    refuses plus tab list in narrativeMarkdown frontmatter reifierpassed3.49 ms
    refuses HTML comment in narrativeMarkdown frontmatter reifierpassed0.42 ms
    refuses setext equals underline in narrativeMarkdown frontmatter reifierpassed0.37 ms
    refuses setext dash underline in narrativeMarkdown frontmatter reifierpassed3.24 ms
    refuses star thematic break in narrativeMarkdown frontmatter reifierpassed3.58 ms
    refuses underscore thematic break in narrativeMarkdown frontmatter reifierpassed0.47 ms
    refuses ordered list in section proseMarkdown frontmatter reifierpassed0.4 ms
    refuses star list in section proseMarkdown frontmatter reifierpassed0.54 ms
    refuses plus list in section proseMarkdown frontmatter reifierpassed0.4 ms
    refuses setext underline in section proseMarkdown frontmatter reifierpassed0.35 ms
    refuses thematic break in section proseMarkdown frontmatter reifierpassed0.33 ms
    refuses bare HTML opener in section proseMarkdown frontmatter reifierpassed10.84 ms
    refuses dash tab list in section proseMarkdown frontmatter reifierpassed0.62 ms
    refuses HTML comment in section proseMarkdown frontmatter reifierpassed0.48 ms
    refuses processing instruction in section proseMarkdown frontmatter reifierpassed0.43 ms
    refuses declaration in section proseMarkdown frontmatter reifierpassed0.38 ms
    refuses mixed-mode Verification headings instead of overwriting the first sectionMarkdown frontmatter reifierpassed3.62 ms
    preserves Behavior rules when an example Intent appears after BehaviorMarkdown frontmatter reifierpassed0.84 ms
    refuses a GWT fence under ModelMarkdown frontmatter reifierpassed0.66 ms
    refuses an H3 under DesignMarkdown frontmatter reifierpassed0.54 ms
    refuses an open question before its H3 ownerMarkdown frontmatter reifierpassed0.49 ms
    refuses an Intent field after the open-questions H3Markdown frontmatter reifierpassed3.79 ms
    refuses frontmatter title through its ruled diagnosticMarkdown frontmatter reifierpassed0.49 ms
    refuses second H1 through its ruled diagnosticMarkdown frontmatter reifierpassed0.36 ms
    refuses near-miss heading through its ruled diagnosticMarkdown frontmatter reifierpassed0.4 ms
    refuses indented list through its ruled diagnosticMarkdown frontmatter reifierpassed0.45 ms
    refuses empty list through its ruled diagnosticMarkdown frontmatter reifierpassed0.41 ms
    refuses nested list through its ruled diagnosticMarkdown frontmatter reifierpassed0.54 ms
    refuses extra heading space through its ruled diagnosticMarkdown frontmatter reifierpassed0.35 ms
    refuses extra list space through its ruled diagnosticMarkdown frontmatter reifierpassed0.37 ms
    refuses invalid GWT phase through its ruled diagnosticMarkdown frontmatter reifierpassed0.47 ms
    refuses late description through its ruled diagnosticMarkdown frontmatter reifierpassed0.4 ms
    refuses raw HTML through its ruled diagnosticMarkdown frontmatter reifierpassed0.35 ms
    refuses inline raw HTML through its ruled diagnosticMarkdown frontmatter reifierpassed0.31 ms
    refuses trailing prose through its ruled diagnosticMarkdown frontmatter reifierpassed0.42 ms
    refuses unsupported block through its ruled diagnosticMarkdown frontmatter reifierpassed0.33 ms
    refuses reserved authored fact through its ruled diagnosticMarkdown frontmatter reifierpassed0.38 ms
    reads a key after the flag and leaves an unkeyed question without oneopen question keys in the Markdown markerpassed0.71 ms
    refuses the carrier whole on a key with an upper-case first letteropen question keys in the Markdown markerpassed0.47 ms
    refuses the carrier whole on a key with an empty keyopen question keys in the Markdown markerpassed0.39 ms
    refuses the carrier whole on a key with a hyphenopen question keys in the Markdown markerpassed0.38 ms
    refuses the carrier whole on a key with a digit firstopen question keys in the Markdown markerpassed0.37 ms
    refuses the carrier whole on a key with a space insideopen question keys in the Markdown markerpassed0.38 ms
    refuses the carrier whole on a key with a non-ASCII letteropen question keys in the Markdown markerpassed0.35 ms
    refuses the carrier whole on a key an earlier question of the Spec carriesopen question keys in the Markdown markerpassed0.75 ms
    keeps distinct keys that differ only in caseopen question keys in the Markdown markerpassed0.93 ms
    keeps today's refusal for a marker with no space before the hashopen question keys in the Markdown markerpassed3.13 ms
    keeps today's refusal for a marker with two spaces before the hashopen question keys in the Markdown markerpassed0.42 ms
    keeps today's refusal for a marker with a key without its hashopen question keys in the Markdown markerpassed1.76 ms
    refuses a keyed question outside its H3 owner as an unkeyed one is refusedopen question keys in the Markdown markerpassed0.51 ms
Design view

Requirement drawing

  • Declared verifying examples: no declared verifying example.
Requirement drawing for spec:carrier.envelope-contract
The diagram as text
  • spec:carrier.envelope-contract: The Markdown envelope is explicit and bounded · declared Spec
  • spec:decisions.envelope-grammar-posture: The Protocol owns the envelope grammar · declared Spec
  • spec:carrier.markdown-authoring: Markdown authoring enters the one graph · declared Spec
  • impl:protocol.envelope-contract: parses the bounded Markdown frontmatter envelope · anchored code · src/extract/markdown-frontmatter.ts:33
  • impl:protocol.markdown-yaml-policy: bounded YAML scalars and relation-target forms · anchored code · src/extract/markdown-yaml-policy.ts:33
  • test:protocol.envelope-contract: frontmatter contract tests verify the Markdown envelope · anchored test binding · binding present · test/markdown-reifier.test.ts:97
  • spec:carrier.envelope-contract refines spec:carrier.markdown-authoring · declared
  • spec:decisions.envelope-grammar-posture refines spec:carrier.envelope-contract · declared
  • impl:protocol.envelope-contract satisfies spec:carrier.envelope-contract · anchored
  • impl:protocol.markdown-yaml-policy satisfies spec:carrier.envelope-contract · anchored
  • test:protocol.envelope-contract verifies spec:carrier.envelope-contract · anchored
Mermaid source

Copyable source; the Studio draws static SVG.

Preferred and chosen syntax: requirementDiagram; exact refines, satisfies and verifies, with claim words in nodes and per-edge comments.

Decisions

Runtime
  • component:protocol.extract · the carrier and source pipeline · src/extract/index.ts:192 · layer application · context protocol

    Uses

    • component:protocol.graph · the one graph and its semantic decisions · src/graph/schema.ts:34 · layer domain · context protocol
    • component:protocol.model · the authored contracts and stable ids · src/model/anchors.ts:100 · layer domain · context protocol
    • component:protocol.notation · the leaf step codec · src/notation/slots.ts:261 · layer domain · context protocol
    • component:protocol.validate · one finding currency and ordered checks · src/validate/validators.ts:72 · layer domain · context protocol
  • impl:protocol.envelope-contract · parses the bounded Markdown frontmatter envelope · src/extract/markdown-frontmatter.ts:33

    Component: component:protocol.extract · the carrier and source pipeline · src/extract/index.ts:192 · layer application · context protocol

    Uses

    None.

  • impl:protocol.markdown-yaml-policy · bounded YAML scalars and relation-target forms · src/extract/markdown-yaml-policy.ts:33

    Component: component:protocol.extract · the carrier and source pipeline · src/extract/index.ts:192 · layer application · context protocol

    Uses

    None.

Runtime observation: not tracked.

Evidence

Runtime observation: not tracked.

Build attestations: not tracked.

Deployments: not tracked.

Bills of materials: not tracked.

Impact
Relations of spec:carrier.envelope-contract
The diagram as text
  • spec:carrier.envelope-contract: The Markdown envelope is explicit and bounded
  • spec:carrier.markdown-authoring: Markdown authoring enters the one graph
  • spec:carrier.markdown-parser: The Markdown parser reifies the ruled subset
  • spec:decisions.envelope-grammar-posture: The Protocol owns the envelope grammar
  • spec:model.relation-reasons: An authored relation may carry its reason
  • spec:model.rule-keys: A rule or flow entry may carry a key that addresses it
  • spec:validation.authored-honesty: Machine truth is never authored
  • spec:carrier.envelope-contract constrainedBy spec:validation.authored-honesty · declared
  • spec:carrier.envelope-contract decidedBy spec:decisions.envelope-grammar-posture · declared
  • spec:carrier.envelope-contract dependsOn spec:model.relation-reasons · declared
  • spec:carrier.envelope-contract dependsOn spec:model.rule-keys · declared
  • spec:carrier.envelope-contract refines spec:carrier.markdown-authoring · declared
  • spec:carrier.markdown-parser dependsOn spec:carrier.envelope-contract · declared
  • spec:decisions.envelope-grammar-posture refines spec:carrier.envelope-contract · declared
Mermaid source

Copyable source; the Studio draws static SVG.

Preferred syntax: flowchart. Chosen syntax: labelled flowchart, preserving exact relations, claims and folds.

Rests on

Rested on by

Distance 1

Distance 2

Distance 3

Distance 4

Distance 5

Distance 6

Distance 7

Distance 8

Distance 9

Relations

Relation and directionOther endClaimReasonExercised keys
constrainedBy · outgoingMachine truth is never authored
spec:validation.authored-honesty · resolves
declaredNoneNone
decidedBy · outgoingThe Protocol owns the envelope grammar
spec:decisions.envelope-grammar-posture · resolves
declaredNoneNone
dependsOn · outgoingAn authored relation may carry its reason
spec:model.relation-reasons · resolves
declaredNoneNone
dependsOn · outgoingA rule or flow entry may carry a key that addresses it
spec:model.rule-keys · resolves
declaredNoneNone
refines · outgoingMarkdown authoring enters the one graph
spec:carrier.markdown-authoring · resolves
declaredNoneNone
dependsOn · incomingThe Markdown parser reifies the ruled subset
spec:carrier.markdown-parser · resolves
declaredNoneNone
refines · incomingThe Protocol owns the envelope grammar
spec:decisions.envelope-grammar-posture · resolves
declaredNoneNone

Bindings

Implementation binding: present

  • impl:protocol.envelope-contract · parses the bounded Markdown frontmatter envelope · src/extract/markdown-frontmatter.ts:33 · role codec · component component:protocol.extract · layer application · context protocol
  • impl:protocol.markdown-yaml-policy · bounded YAML scalars and relation-target forms · src/extract/markdown-yaml-policy.ts:33 · role codec · component component:protocol.extract · layer application · context protocol

Design reference: none

Verifier binding: present

  • test:protocol.envelope-contract · frontmatter contract tests verify the Markdown envelope · anchored · test/markdown-reifier.test.ts:97 · test anchor

Expected-outcome oracle: none

Runtime observation: not tracked.

Run results: not recorded in the graph.

Findings

None.

Composing (0)

Composing needs the script.