Verification and traceability

Platform spec article

Verification and traceability

Back to ANSI escape model ◎ Open feature in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (4)

1. 0001-dec-save-restore-cursor DEC save/restore cursor pair Accepted

   Normative cursor save/restore uses DEC sequences, not SCO.

   Context

   Authors need portable cursor stacking without SCO-specific CSI variants in typed builders.

   Decision

   Rule	Detail
   Save/restore	DEC ESC 7 / ESC 8 is the normative pair
   SCO	CSI s / CSI u are not required in v1 typed builders

   Consequences

   Typed Ansi.Cursor helpers emit DEC only; raw Csi may still be used in tests.

   Verification anchors

   AnsiEscapeTests.bd; ANSI.md tables.

   Open full ADR page

2. 0002-capability-gating-strips-ansi Capability gating strips ANSI Accepted

   Styled emission must respect ShouldEmitAnsi and non-TTY hosts.

   Context

   Programs must not leak escapes to pipes, log files, or NO_COLOR environments.

   Decision

   Rule	Detail
   Gating	User-visible styled output must pass Ansi.Escape.WhenEnabled
   Tests	Ungated Csi remains for golden tests

   Consequences

   When ShouldEmitAnsi() is false, gated builders return empty strings.

   Verification anchors

   AnsiEscapeTests.bd; console capability integration.

   Open full ADR page

3. 0003-sgr-color-downgrade-ladder SGR color downgrade ladder Accepted

   Truecolor sequences downgrade via EffectiveColorModel.

   Context

   Terminals differ in color depth; emitting unsupported 38;2 breaks dumb hosts.

   Decision

   Rule	Detail
   Ladder	truecolor → 256 → basic per EffectiveColorModel
   Policy	Callers do not pick per-sequence models manually

   Consequences

   SGR builders consult capability probes before emitting RGB CSI.

   Verification anchors

   AnsiSgrGoldenTests.bd; CapabilitiesTests.bd.

   Open full ADR page

4. 0004-osc-bel-termination-v1 OSC BEL termination in v1 Accepted

   OSC payloads terminate with BEL, not ST.

   Context

   OSC framing varies across terminals; v1 picks one terminator for golden tests.

   Decision

   Rule	Detail
   Terminator	BEL (0x07) in v1
   ST	ESC termination is not required

   Consequences

   OSC helpers emit BEL-terminated sequences only until a future ADR extends ST.

   Verification anchors

   AnsiEscapeTests.bd; Ansi.Osc sources.

   Open full ADR page

Articles

• Contracts and edge cases MUST/SHOULD rules for escape emission and supported sequence subsets. article Standard Reviewed Thu May 21
• Design model ESC/CSI/OSC taxonomy and normative control-character tables for terminal output. article Standard Reviewed Thu May 21
• Examples Representative escape composition and gated emission patterns. article Standard Reviewed Thu May 21
• Flow and algorithm How escape bytes are composed, gated, and written to stdout. article Standard Reviewed Thu May 21
• Verification and traceability Golden tests and source anchors for ANSI escape framing. article Standard Reviewed Thu May 21

History

0 revisions (git unavailable at build; counts may be empty)

Open full history on GitHub

No commits recorded for this path.

Completeness

OKfeature · 3 SpecSection(s) · 1 H2 heading(s)

Section id	Required	Found
what-this-feature-specifies	yes	yes
implementation-anchors	yes	yes

Full tree: run pnpm verify:platform-spec-layout (writes src/generated/platform-spec-layout-report.json).

Related spec docs

• Feature
  ANSI escape model

  Parent feature hub

Purpose

Document verification and traceability for the Ansi Escape Model feature: role-specific normative detail beyond the feature hub.

Canonical references

• Feature hub: Ansi Escape Model
• Sibling articles in this bundle (design model, contracts, flow, examples, verification)

Detailed behavior

Source anchors

Path	Coverage
compiler/corelib/packages/console/src/Ansi/Escape.bd	ESC, CSI, private mode, DEC, OSC, gating
compiler/corelib/packages/console/src/Ansi/Cursor.bd	Movement CSI
compiler/corelib/packages/console/src/Ansi/Erase.bd	Display/line erase
compiler/corelib/packages/console/src/Ansi/Sgr.bd	SGR builder and downgrade
compiler/corelib/packages/console/src/Ansi/Screen.bd	Scroll region / alt screen
Repository ANSI.md	Informative full sequence catalog

Corelib tests

Test file	Asserts
AnsiEscapeTests.bd	CSI bold red, reset, ?1049h, DEC save, cursor home, erase display
AnsiSgrGoldenTests.bd	SGR chains and reset suffix
AnsiStyleChainTests.bd	Markup attribute chain → escapes
AnsiBuildersTests.bd	Screen scroll region framing
CapabilitiesTests.bd	Gated vs empty output when ANSI disabled

Tests live under compiler/corelib/beskid_corelib/tests/corelib_tests/src/console/ and run as part of the corelib_tests project.

Traceability rule

Any change to ANSI-001 through ANSI-008 in contracts and edge cases must update or add a golden test in the same change. Informative ANSI.md updates are recommended but not CI-gated.

Verification

See the verification and traceability article in this bundle and compiler/corelib/beskid_corelib/tests/corelib_tests/src/console/.

Related topics

• Parent feature hub and Terminal and console area