@termwright/conformance 0.2.0 → 0.3.0

package/README.md

@@ -35,7 +35,6 @@ await runAdapterConformance({
   quit: { input: '', exitCode: 0 },
   columns: 80,
   rows: 24,
-  expectAbsoluteBounds: true,
 });
 ```
 
@@ -103,17 +102,16 @@ stderr rather than failing the run.
 
 It checks the five obligations an adapter has:
 
-| Obligation | What is asserted |
-|---|---|
-| Dormant rule | Without `TERMWRIGHT_ENDPOINT` it opens no channel and writes no marker; with `baseline`, byte-for-byte identical startup output |
-| Tree before input | Once the handshake completes and *before any input*, the tree is non-empty and has at least one node a locator could address. Opt out with `treeBeforeInput: {required: false, reason}` |
-| Handshake | `hello` first and once, correct protocol id, non-empty adapter identity, capabilities from the closed set |
-| Snapshot validity | Every snapshot passes `validateSnapshot`, carries this session's id, has resolvable parents and monotonic revisions |
-| Revision ordering | For each revision: snapshot → `revision-commit` → a marker that verifies against the session token, markers strictly increasing |
-| Channel loss | Cutting the socket leaves the application rendering and alive, and the adapter does not reconnect |
-| Logs | An adapter that did not announce `logs` sends none. One that declares them in the registration must deliver a record whose `seq` is unique and increasing and whose message never appears on the terminal |
-| Deltas (when announced) | With `subscribe: 'diffs'`, the deltas an adapter emits compose — through the protocol's own `applyTreeDelta` — to the same tree it reports when asked with `get-tree` |
-| Conventions | The machine-checkable half of the protocol README's "Adapter semantics conventions": containers are not named from their content (rule 2), an annotated test id reaches the wire (rule 3), an empty textbox publishes `value: ''` and no value is derived outside `{textbox, progressbar}` or from a boolean (rule 5) |
+| Obligation        | What is asserted                                                                                                                                                                                                                                                                                                      |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Dormant rule      | Without `TERMWRIGHT_ENDPOINT` it opens no channel and writes no marker; with `baseline`, byte-for-byte identical startup output                                                                                                                                                                                       |
+| Tree before input | Once the handshake completes and _before any input_, the tree is non-empty and has at least one node a locator could address. Opt out with `treeBeforeInput: {required: false, reason}`                                                                                                                               |
+| Handshake         | `hello` first and once, correct protocol id, non-empty adapter identity, capabilities from the closed set                                                                                                                                                                                                             |
+| Snapshot validity | Every publication is a complete v2 snapshot that passes `validateSnapshot`, carries this session's id, has resolvable parents and monotonic revisions                                                                                                                                                                 |
+| Revision ordering | For each revision: snapshot → `revision-commit` → a marker that verifies against the session token, markers strictly increasing                                                                                                                                                                                       |
+| Channel loss      | Cutting the socket leaves the application rendering and alive, and the adapter does not reconnect                                                                                                                                                                                                                     |
+| Logs              | An adapter that did not announce `logs` sends none. One that declares them in the registration must deliver a record whose `seq` is unique and increasing and whose message never appears on the terminal                                                                                                             |
+| Conventions       | The machine-checkable half of the protocol README's "Adapter semantics conventions": containers are not named from their content (rule 2), an annotated test id reaches the wire (rule 3), an empty textbox publishes `value: ''` and no value is derived outside `{textbox, progressbar}` or from a boolean (rule 5) |
 
 `await` it at the top level: `vitest` is imported dynamically so the package can
 also be used from a plain script.
@@ -123,12 +121,12 @@ also be used from a plain script.
 `CONFORMANCE_FIXTURES` returns absolute paths to programs you can launch with
 `node <path>`:
 
-| Fixture | Purpose | Dependencies |
-|---|---|---|
-| `generic()` | Uninstrumented app: menu, colours, mouse/paste/focus modes, Unicode, alternate screen, scrollback (§20.1) | none |
-| `prompt()` | Shell-shaped app emitting OSC 133 marks; `--marks=off` suppresses them, `--work=<ms>` sets the command duration | none |
-| `adversarialPeer()` | Raw wire peer; takes a scenario name as `argv[2]` (§20.3) | none |
-| `inkProbe()` | Ordinary `ink.render` app launched through the zero-config Ink probe | `ink`, `react`, `@termwright/probe-ink` |
+| Fixture             | Purpose                                                                                                         | Dependencies                            |
+| ------------------- | --------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
+| `generic()`         | Uninstrumented app: menu, colours, mouse/paste/focus modes, Unicode, alternate screen, scrollback (§20.1)       | none                                    |
+| `prompt()`          | Shell-shaped app emitting OSC 133 marks; `--marks=off` suppresses them, `--work=<ms>` sets the command duration | none                                    |
+| `adversarialPeer()` | Raw wire peer; takes a scenario name as `argv[2]` (§20.3)                                                       | none                                    |
+| `inkProbe()`        | Ordinary `ink.render` app launched through the zero-config Ink probe                                            | `ink`, `react`, `@termwright/probe-ink` |
 
 The first three import nothing at all — the adversarial peer re-derives the
 framing and the marker MAC from the specification rather than importing
@@ -151,27 +149,38 @@ keep running, and only a pid probed afterwards tells the two apart.
 
 ```sh
 pnpm --filter @termwright/conformance conformance     # every suite, one matrix
+pnpm --filter @termwright/conformance conformance --require-declared-skips
+pnpm --filter @termwright/conformance conformance --require-no-skipped-areas
 pnpm --filter @termwright/conformance test            # plain vitest
 pnpm --filter @termwright/conformance test:hostile    # adversarial suite, 128 MB heap cap
 ```
 
-```
-area                        spec     result         tests    time
-generic fallback            §20.1    pass           10/10    2.0s
-hostile peer                §20.3    pass           25/25    14.5s
-interaction                 §20.4    pass           12/12    2.6s
-readiness + env             §5.3     pass           10/10    2.2s
-adapter contract (py/go)    §7       pass, 8 skip   6/14     0.6s
-hostile peer @ 128 MB heap  §10      pass           25/25    14.4s
-```
+The conformance orchestrator builds the probed and plain tview fixtures
+asynchronously before the native test host is opened. Each run gets a private
+temporary directory and a platform/architecture contract containing both
+binary digests. Collection only verifies that contract and never launches a
+compiler; the orchestrator removes the directory after the host closes.
+
+The table reports each area as pass, fail, or pass with an explicit skip count;
+the exact test counts intentionally are not documentation because suites grow.
+Test identities use `file::fullName`, so declarations cannot accidentally
+match a same-named test elsewhere.
 
 Certifying the py/go rows needs their toolchains on the runner
 (`pip install -e clients/python[dev]` and a Go toolchain); without them those
 rows skip honestly, with the probe's failure on stderr.
 
-A partly-skipped area is reported as such rather than as a clean pass: the
-language adapters skip their whole registration when the toolchain is absent,
-and a matrix that hid it would claim coverage the machine never produced.
+A partly-skipped area is reported as such rather than as a clean pass. Platform
+deviations live in the reviewed registry and must match the exact test identity.
+`--require-declared-skips` requires the observed skip identities to equal the
+reviewed applicability and platform-deviation registries exactly.
+`--require-no-skipped-areas` is stricter: it permits only the fixed
+applicability skips and rejects every registered platform deviation. Vitest
+implements applicability with `skipIf`/`runIf`, so those cases do appear in the
+matrix as expected skips even though they are not missing platform coverage.
+Local runs may honestly skip a missing optional toolchain, while certification
+installs its prerequisites and requires exact declared skips so missing
+coverage cannot look green.
 
 Sessions launch with the driver's secret-safe `envMode: 'replace'` default, so
 a fixture only sees the documented allowlist plus what a suite declares.

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { AdapterToDriverMessage, LogRecord, TreeDelta, SemanticSnapshot } from '@termwright/protocol';
+import { AdapterToDriverMessage, LogRecord } from '@termwright/protocol';
 import { LaunchOptions, TerminalHarness } from '@termwright/driver';
 
 /** How a fixture is started. Everything else about it is opaque to the probe. */
@@ -31,12 +31,6 @@ interface ProbeOptions {
     readonly rows?: number;
     /** Set `false` to withhold the instrumentation env — the dormant-run case. */
     readonly instrument?: boolean;
-    /**
-     * What the probe asks the adapter to push. `'diffs'` is a preference, not a
-     * prohibition: an adapter may still send a full tree when a delta would not
-     * pay for itself, and the first publication always is one.
-     */
-    readonly subscribe?: 'snapshots' | 'diffs';
 }
 /** Everything the probe observed, readable while the child is still running. */
 interface ProbeObservation {
@@ -51,17 +45,6 @@ interface ProbeObservation {
     readonly screen: string;
     /** Application log records the adapter sent, in arrival order. */
     readonly logs: readonly LogRecord[];
-    /** Deltas the adapter sent, in arrival order. */
-    readonly deltas: readonly TreeDelta[];
-    /**
-     * The tree obtained by composing every snapshot and delta received, in order,
-     * with the protocol's own `applyTreeDelta`. This is the oracle an adapter's
-     * deltas are checked against: a producer that also composed would only prove
-     * it agrees with itself.
-     */
-    readonly composed: SemanticSnapshot | null;
-    /** Why composition stopped, when it did. A conforming adapter produces none. */
-    readonly compositionError: string | null;
 }
 /**
  * Runs one fixture under a pseudo-terminal with a protocol endpoint attached.
@@ -122,13 +105,6 @@ declare class AdapterProbe {
     cutChannel(): void;
     /** Stops the child and releases the endpoint. Idempotent. */
     stop(): Promise<void>;
-    /**
-     * Asks the adapter for a full tree and resolves with it.
-     *
-     * This is what turns composition into a check rather than a belief: the
-     * locally composed tree is compared against one the adapter built itself.
-     */
-    requestTree(timeoutMs?: number): Promise<SemanticSnapshot | null>;
 }
 /** The marker prefix, re-exported so suites can assert on dormant output. */
 declare const MARKER_TEXT_PREFIX = "\u001B]8487;twm;";
@@ -173,8 +149,8 @@ interface AdapterConformanceOptions {
     };
     readonly columns?: number;
     readonly rows?: number;
-    /** Assert that published bounds are viewport-absolute (an `absolute-bounds` claim). */
-    readonly expectAbsoluteBounds?: boolean;
+    /** Assert that intended geometry is authoritative in viewport cells. */
+    readonly expectIntendedGeometry?: boolean;
     /**
      * Opt out of the "publishes a tree before any input" obligation.
      *
@@ -240,8 +216,9 @@ interface AdapterConformanceOptions {
     /** How long the handshake may take. Default 10 s. */
     readonly timeoutMs?: number;
     /**
-     * A command that must succeed before this adapter can be certified here —
-     * its interpreter, or a build step that produces the binary `spawn` runs.
+     * A cheap command that must succeed before this adapter can be certified here.
+     * Compilers and other descendant-producing preparation must run before the
+     * native host opens; this probe is collection-time capability validation only.
      * When it fails the whole suite skips and the reason is in the block's name,
      * exactly as a missing pseudo-terminal does.
      */
@@ -250,6 +227,7 @@ interface AdapterConformanceOptions {
         readonly label: string;
         readonly cwd?: string;
         readonly timeoutMs?: number;
+        readonly env?: Readonly<Record<string, string>>;
     };
 }
 /**
@@ -311,8 +289,8 @@ declare const CONFORMANCE_FIXTURES: Readonly<{
 /**
  * Whether this machine can open a pseudo-terminal at all.
  *
- * @returns `false` when `TERMWRIGHT_SKIP_PTY=1` or spawning a trivial child
- * through the PTY backend throws. Probed once and cached.
+ * @returns `false` when `TERMWRIGHT_SKIP_PTY=1` or the native binding cannot
+ * be loaded and validated. Real child creation remains inside a test attempt.
  */
 declare function ptyAvailable(): boolean;
 /** `process.env` with the `undefined` values dropped, as PTY spawning requires. */