A TypeScript-carried Spec can be converted to Markdown

actor

A coding agent or maintainer.

outcome

Convert a TypeScript-carrier Spec into an idiomatic Markdown carrier beside its source.

value

The TypeScript DSL remains an import source and a lawful per-ID option; the author chooses which carrier remains canonical.

rule line 18 · specs/carrier/sdp-import.sdp.md:18

Import writes the emitted Markdown sibling beside the TypeScript carrier and never deletes the source carrier.

rule line 19 · specs/carrier/sdp-import.sdp.md:19

A written Markdown sibling and its retained TypeScript source carry the same Spec id; before extracting both paths in one root, the author keeps one canonical surface by moving, renaming, excluding or removing the source, and the import success message explains this hand-off.

rule line 20 · specs/carrier/sdp-import.sdp.md:20

Import refuses an existing Markdown sibling rather than overwriting it.

rule line 21 · specs/carrier/sdp-import.sdp.md:21

Refusal outcomes retain the TypeScript reifier findings and add import-local findings honestly.

rule line 22 · specs/carrier/sdp-import.sdp.md:22

Import consumes the TypeScript reifier so source acceptance follows one validation path.

rule line 23 · specs/carrier/sdp-import.sdp.md:23

Import accepts only carriers whose builders come from the public package or its /anchors subpath; a relative builder import that a source checkout trusts during extraction is refused here.

rule line 24 · specs/carrier/sdp-import.sdp.md:24

sdp import converts Spec carriers; Pack manifests are out of scope — the TypeScript manifest stays a lawful per-ID option.

rule line 25 · specs/carrier/sdp-import.sdp.md:25

A batch walks only ordinary directory entries in requested source directories, skips dot-directories and node_modules, dist, generated and coverage, selects .sdp.ts files, canonicalizes physical carrier identity, and computes refusals and target collisions before publishing.

rule line 26 · specs/carrier/sdp-import.sdp.md:26

Publication prepares exclusive temporary siblings and atomically creates targets without clobbering; rollback attempts every artifact, reports survivors, and never deletes a TypeScript source.

9 unkeyed rules.

Verifying examples

Given a TS-carrier spec
When importTypeScriptSpec runs
Then the emitted Markdown re-parses to an equal graph

Example space

Given a TS-carrier spec
When importTypeScriptSpec runs
Then the emitted Markdown re-parses to an equal graph

findingIds line 29 · specs/carrier/sdp-import.sdp.md:29

import/refusal, import/pack-unsupported, import/target-exists, import/unsupported-construct, import/invalid-source-path, import/no-sources and import/empty name the importer's findings; retained TypeScript reifier findings keep their own ids.

no citation recorded

dryRun line 30 · specs/carrier/sdp-import.sdp.md:30

sdp import <path...> --dry-run computes refusals and target collisions, prints the planned Markdown siblings and writes none.

no citation recorded

Verifier bindings

• spec:carrier.sdp-import.round-trip · A TypeScript carrier survives import as an equal Markdown graph · declared · example enabled · specs/carrier/sdp-import.round-trip.sdp.md

  External run evidence from test/self-hosting-sdp-import.test.ts

  Test anchors: test:protocol.sdp-import.round-trip. Specs verified by those bindings: spec:carrier.sdp-import, spec:carrier.sdp-import.round-trip.

  Run 1: external run evidence from vitest 4.1.10

  Build: CI 391 · Branch: cursor/media-plan-and-articles-09b1 · Commit: 076cd4f1f85640d8236e5cca1bffffa68ab79a33 · Start: 2026-10-31T15:32:20.471Z · Stop: 2026-10-31T15:34:02.073Z

  Name	Suite	Result	Duration
  executes the bound example against a fresh world	A TypeScript carrier survives import as an equal Markdown graph (spec:carrier.sdp-import.round-trip)	passed	56.64 ms

Requirement drawing

Decisions

• Markdown is the default Spec carrier

  Specs default to Markdown; Packs remain TS until a Pack syntax ruling; the TS DSL survives as import source and a lawful per-ID option. Later refinements keep this default and the one-surface law without repealing them: the Pack syntax ruling completes Pack Markdown, and the Gherkin carrier option admits graph-aware Gherkin as a lawful per-ID option for behavior and example Specs only, with the canonical suffix settled as .sdp.gherkin.

• component:protocol.cli · entry points, shared build and publication · src/cli/build-command.ts:32 · layer edge · context protocol

  Uses

  • component:protocol.adapters · external runtime and source adapters · src/adapters/vitest.ts:23 · layer adapter · context protocol
  • component:protocol.codegen · contracts and registrar output · src/codegen/contracts.ts:633 · layer application · context protocol
  • component:protocol.extract · the carrier and source pipeline · src/extract/index.ts:192 · layer application · context protocol
  • component:protocol.graph · the one graph and its semantic decisions · src/graph/schema.ts:34 · layer domain · context protocol
  • component:protocol.import · canonical conversion with a fidelity boundary · src/import/import.ts:45 · layer application · context protocol
  • component:protocol.model · the authored contracts and stable ids · src/model/anchors.ts:100 · layer domain · context protocol
  • component:protocol.projections · read-only output, layout and owned publication · src/projections/design-review.ts:29 · layer edge · context protocol
  • component:protocol.reader · the typed graph contract and body evaluator · src/reader/reader.ts:671 · layer application · context protocol
  • component:protocol.validate · one finding currency and ordered checks · src/validate/validators.ts:72 · layer domain · context protocol
• component:protocol.import · canonical conversion with a fidelity boundary · src/import/import.ts:45 · layer application · context protocol

  Uses

  • component:protocol.extract · the carrier and source pipeline · src/extract/index.ts:192 · layer application · 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.import-fidelity · refuses Markdown emission that changes authored meaning · src/import/markdown-fidelity.ts:102

  Component: component:protocol.import · canonical conversion with a fidelity boundary · src/import/import.ts:45 · layer application · context protocol

  Uses

  None.

• impl:protocol.sdp-import · plans, refuses, and publishes TypeScript-to-Markdown Spec imports · src/cli/import-command.ts:71

  Component: component:protocol.cli · entry points, shared build and publication · src/cli/build-command.ts:32 · layer edge · context protocol

  Uses

  None.

• impl:protocol.sdp-import-core · converts a TypeScript-carrier Spec into an idiomatic Markdown twin · src/import/import.ts:58

  Component: component:protocol.import · canonical conversion with a fidelity boundary · src/import/import.ts:45 · layer application · context protocol

  Uses

  None.

• impl:protocol.sdp-import-markdown-emit · emits the Markdown document twin for an imported Spec · src/import/emit-markdown.ts:253

  Component: component:protocol.import · canonical conversion with a fidelity boundary · src/import/import.ts:45 · layer application · context protocol

  Uses

  None.

• impl:protocol.sdp-import-publish · stages Markdown siblings and publishes them with atomic hard links · src/cli/import-publish.ts:23

  Component: component:protocol.cli · entry points, shared build and publication · src/cli/build-command.ts:32 · layer edge · context protocol

  Uses

  None.

• impl:protocol.sdp-import-scan · collects .sdp.ts paths and reports scan failures · src/cli/import-scan.ts:62

  Component: component:protocol.cli · entry points, shared build and publication · src/cli/build-command.ts:32 · layer edge · context protocol

  Uses

  None.

Runtime observation: not tracked.

Runtime observation: not tracked.

Build attestations: not tracked.

Deployments: not tracked.

Bills of materials: not tracked.