@polyengine/ct-runner 0.1.0-pre.g633468a

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,23 @@
+# @polyengine/ct-runner
+
+The polyengine execution runner for component-test-results (L1) conformance suites.
+
+Part of [polyengine](https://github.com/polymorph-components/polyengine), a
+WebAssembly Component Model host for JavaScript engines. This is the npm
+distribution; the same package is published to JSR as `jsr:@polyengine/ct-runner`, and the
+two are built from the same sources at the same version.
+
+```sh
+npm install @polyengine/ct-runner
+```
+
+```js
+import * as api from "@polyengine/ct-runner";
+```
+
+Entry points: `.`, `./context`, `./imports`, `./run`.
+
+ESM only, Node >= 22.14. Documentation, examples and the embedder API contract
+live in the [repository](https://github.com/polymorph-components/polyengine).
+
+Apache-2.0.

package/esm/context.js

@@ -0,0 +1,48 @@
+// The host-side `test-context` provider (L1 contract's runner-side growth
+// surface): a host-implemented resource class per contracts/embedder-api.md
+// §"Resources" (host provides a plain class; the runtime owns instance<->rep
+// mapping). The `context` resource's `diagnostic` is an `async func` import
+// (WIT: wit/tests.wit `test-context.diagnostic: async func(msg: string)`,
+// vendored at examples/guests/test-suite/wit/tests.wit) — per
+// contracts/embedder-api.md §"Functions and async", an async-func import may
+// be a plain `async` JS function.
+//
+// ARCHITECTURE.md Rule 3 ("introspecting host runner"): this file *is* the L2
+// context-provider component, reimplemented host-side rather than composed in
+// as wasm — permitted as long as it stays behaviorally equivalent to the
+// layered path. It must never grow beyond what `test-context` names.
+/** The frozen L1 interface id `test-context` is provided under. */
+export const TEST_CONTEXT_INTERFACE = "polymorph:test/test-context@0.1.0";
+/**
+ * One case's diagnostic sink. Host-side: no reps, no side tables — see
+ * contracts/embedder-api.md's host-implemented-resource column.
+ *
+ * `diagnostic` "may block cooperatively" per the WIT doc comment; this
+ * in-process host implementation never blocks (no backpressure to model),
+ * so it resolves immediately — still a valid `async func` implementation
+ * (contracts/embedder-api.md: "sync implementations remain legal").
+ */
+export class Context {
+    #onDiagnostic;
+    constructor(onDiagnostic) {
+        this.#onDiagnostic = onDiagnostic;
+    }
+    // deno-lint-ignore require-await
+    async diagnostic(msg) {
+        this.#onDiagnostic(msg);
+    }
+}
+/**
+ * Build the `test-context` import-record entry
+ * (`{ [TEST_CONTEXT_INTERFACE]: { Context } }`), per contracts/embedder-api.md
+ * §"Module wiring and instantiation" (resource classes sit at the resource's
+ * position in the record, PascalCase).
+ *
+ * The class is registered once per `instantiate` call regardless of how many
+ * cases run against that instance; the runner never asks the guest to
+ * construct a `context` (the WIT resource has no constructor — the host
+ * always initiates the borrow itself when calling `run`).
+ */
+export function testContextImportRecord() {
+    return { [TEST_CONTEXT_INTERFACE]: { Context } };
+}

package/esm/import-analysis.js

@@ -0,0 +1,67 @@
+// Translate-only import analysis: `requiredImports()` (contracts/embedder-api.md
+// §"Module wiring and instantiation") plus the runner's own test-context
+// auto-wiring policy, without ever instantiating the suite. Used both by
+// `runSuite` (to fail fast, before an async instantiate) and standalone (the
+// "translate-only acceptance" gate: enumerate what a not-yet-executable suite
+// is missing, without trying to run it).
+import { NameCollisionError, requiredImports, } from "@polyengine/runtime/embedder";
+import { ImportResolver } from "@polyengine/runtime/embedder";
+import { TEST_CONTEXT_INTERFACE } from "./context.js";
+/** One or more of the suite's import leaves cannot be resolved (yet). */
+export class MissingImportsError extends Error {
+    /** The unresolved leaves, in `requiredImports()` order. */
+    leaves;
+    /** The distinct top-level record keys (interface ids / bare names) missing. */
+    missing;
+    constructor(missing, leaves) {
+        super(`suite is missing ${missing.length} host import(s): ` +
+            missing.map((m) => `'${m}'`).join(", "));
+        this.name = "MissingImportsError";
+        this.missing = missing;
+        this.leaves = leaves;
+    }
+}
+/**
+ * Analyze a suite's import surface against a caller-provided imports record,
+ * WITHOUT instantiating anything (translate-only; `requiredImports` reads
+ * only the plan). Detects:
+ *  - whether `test-context` is imported (only then does the runner provide
+ *    it — pre-composed bundles with the provider already linked must work
+ *    too, per the dispatch);
+ *  - a caller/runner collision on `test-context` (the runner "merges,
+ *    erroring on collisions" per the dispatch's import-wiring spec);
+ *  - every other top-level import key the suite needs but `provided` lacks,
+ *    via the same version-canonical resolution `instantiate` itself uses
+ *    (`ImportResolver`, contracts/embedder-api.md §"Version canonicalization").
+ */
+export function analyzeImports(plan, provided = {}) {
+    const leaves = requiredImports(plan);
+    const requiresTestContext = leaves.some((l) => l.interfaceId === TEST_CONTEXT_INTERFACE);
+    if (requiresTestContext && TEST_CONTEXT_INTERFACE in provided) {
+        throw new NameCollisionError(`'${TEST_CONTEXT_INTERFACE}' was provided explicitly, but this suite ` +
+            `imports test-context and the ct-runner always supplies it itself ` +
+            `(contracts/embedder-api.md's "merges, erroring on collisions" ` +
+            `policy). Remove it from your imports record — a pre-composed ` +
+            `bundle that already links a provider should not import ` +
+            `test-context in the first place.`);
+    }
+    const resolver = new ImportResolver(provided);
+    const groups = new Set(leaves.map((l) => l.interfaceId));
+    const missing = [];
+    for (const id of groups) {
+        if (requiresTestContext && id === TEST_CONTEXT_INTERFACE)
+            continue; // the runner supplies it
+        if (resolver.resolve(id) === undefined)
+            missing.push(id);
+    }
+    return { leaves, requiresTestContext, missing };
+}
+/** `analyzeImports`, throwing `MissingImportsError` if anything is missing. */
+export function requireImportsResolved(plan, provided = {}) {
+    const analysis = analyzeImports(plan, provided);
+    if (analysis.missing.length > 0) {
+        const leaves = analysis.leaves.filter((l) => analysis.missing.includes(l.interfaceId));
+        throw new MissingImportsError(analysis.missing, leaves);
+    }
+    return analysis;
+}

package/esm/mod.js

@@ -0,0 +1,12 @@
+// ct-runner: polyengine's L3 execution runner for polymorph-test's L1
+// suite contract (TRACK C2-D; docs/consumers.md, C2).
+//
+// "Execute an L1 suite component, emit canonical results JSONL (L4)" — an
+// introspecting host runner (ARCHITECTURE.md Rule 3): it drives
+// `polymorph:test/tests@0.1.0` directly against a host-side `test-context`
+// provider, never composing wasm for L2. See src/run-suite.ts for the case
+// loop and src/context.ts for the host resource.
+export { runSuite, TESTS_INTERFACE, } from "./run-suite.js";
+export { analyzeImports, MissingImportsError, requireImportsResolved, } from "./import-analysis.js";
+export { Context, TEST_CONTEXT_INTERFACE, testContextImportRecord } from "./context.js";
+export { applies, collectTagsSections, firstExcluding, loadTagsInventory, parseTagsRecords, TAGS_SECTION, tagsOf, } from "./tags.js";

package/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/esm/run-suite.js

@@ -0,0 +1,299 @@
+// The L3 case-loop driver: instantiate the suite behind the embedder
+// conventions, enumerate cases, execute them, emit canonical L4 results
+// JSONL. Mirrors the semantics of polymorph-test's own JS legs
+// (js/viewer/harness.mjs `runCases`/`runSuiteJsonl`) rather than reinventing
+// a policy — an "introspecting host runner" per ARCHITECTURE.md Rule 3 must
+// stay behaviorally equivalent to the layered path.
+//
+// L4 schema authority: polymorph-test crates/component-test-results/src/lib.rs
+// (`Envelope`, `RunInfo`, `CaseResult`, `Status`, `Provenance`,
+// `wire_vocabulary_pinned` test) — the canonical wire types; cross-checked
+// against expected/verify-pipeline-fixture.jsonl and
+// expected/verify-compose-sample.jsonl (golden samples of the same format).
+import { instantiate, Trap, ComponentException, } from "@polyengine/runtime/embedder";
+import { Context, testContextImportRecord } from "./context.js";
+import { requireImportsResolved } from "./import-analysis.js";
+import { applies, firstExcluding, loadTagsInventory, tagsOf, } from "./tags.js";
+/** The suite's `tests` interface id (wit/tests.wit `interface tests`, v0.1.0). */
+export const TESTS_INTERFACE = "polymorph:test/tests@0.1.0";
+/** `js/viewer/harness.mjs`'s `resolveTestsExport`, ported: the suite's
+ * `tests` interface from an instantiated component, whichever spelling the
+ * producer used (verbatim interface id is what this runtime always uses,
+ * but the fallback costs nothing and documents the contract). */
+// deno-lint-ignore no-explicit-any
+function resolveTestsExport(exports) {
+    const tests = exports[TESTS_INTERFACE] ?? exports["tests"];
+    if (tests === undefined) {
+        throw new Error(`suite instance exports no '${TESTS_INTERFACE}' interface: ` +
+            `${Object.keys(exports)}`);
+    }
+    return tests;
+}
+async function sha256Hex(bytes) {
+    const digest = await crypto.subtle.digest("SHA-256", bytes.slice().buffer);
+    return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}
+function describeThrow(e) {
+    return e instanceof Error ? `${e.name}: ${e.message}` : String(e);
+}
+/**
+ * Run one suite end to end: instantiate, enumerate, execute every case,
+ * emit the complete results-JSONL stream (envelope, one line per case,
+ * terminator) through `opts.emit`. Throws `MissingImportsError` up front
+ * (contracts/embedder-api.md's `requiredImports`) if the caller's imports
+ * cannot satisfy the suite, and a plain `Error` if the census is empty (an
+ * empty selection is a run error, per component-test-results/src/lib.rs's
+ * `fold_jsonl` and harness.mjs's `runSuiteJsonl` — both refuse it).
+ */
+export async function runSuite(artifacts, opts) {
+    const provided = opts.imports ?? {};
+    // Fail fast, translate-only, before any instantiate (gate 3's contract):
+    // detect whether test-context is imported at all — a pre-composed bundle
+    // with the provider already linked in must work with no test-context
+    // wiring — and merge, erroring on any caller/runner collision.
+    const analysis = requireImportsResolved(artifacts.plan, provided);
+    const mergedImports = analysis.requiresTestContext
+        ? { ...provided, ...testContextImportRecord() }
+        : provided;
+    const freshCases = opts.freshCases ?? true;
+    // Validate `shard` loudly (issue #110): integers, count >= 1, index in
+    // [0, count). Fail fast, before any instantiate, same posture as the
+    // imports/tags validation above.
+    if (opts.shard !== undefined) {
+        const { index, count } = opts.shard;
+        if (!Number.isInteger(count) || count < 1) {
+            throw new Error(`shard.count must be an integer >= 1, got ${count}`);
+        }
+        if (!Number.isInteger(index) || index < 0 || index >= count) {
+            throw new Error(`shard.index must be an integer in [0, ${count}), got ${index}`);
+        }
+    }
+    const newTests = async () => {
+        const inst = await instantiate(artifacts, mergedImports, {
+            jspi: opts.jspi,
+        });
+        return resolveTestsExport(inst.exports);
+    };
+    const censusTests = await newTests();
+    const census = await censusTests.all();
+    // Feature-tag scheduling (issue #25): gate on the suite's own
+    // `component-test:tags@0.1` inventory when it has one — the SDK embeds it
+    // in the guest core module and it survives wac composition, so this
+    // introspecting runner CAN see it (revising the earlier "cannot see the
+    // tags section" stance recorded below). Suites without an inventory run
+    // feature-blind exactly as before.
+    const inventory = loadTagsInventory(artifacts.componentBytes);
+    const missing = opts.missing ?? [];
+    if (inventory === null && opts.missing !== undefined) {
+        throw new Error("missing-features given, but the suite carries no " +
+            "component-test:tags@0.1 inventory (not built with their SDK, or " +
+            "sections stripped) — tag gating is impossible, refusing to " +
+            "silently run feature-blind");
+    }
+    const suiteName = opts.suiteName.replaceAll("-", "_");
+    const artifactSha256 = await sha256Hex(artifacts.componentBytes);
+    opts.emit(JSON.stringify({
+        "component-test-results": "0.1",
+        target: opts.target,
+        suite: { name: suiteName, "artifact-sha256": artifactSha256 },
+        // "tags" when this run schedules against the suite's tag inventory,
+        // "none" for inventory-less suites (component-test-results/src/lib.rs
+        // `RunInfo`: "none" is for producers that cannot see the tags section
+        // — with the inventory in hand, this runner no longer is one).
+        run: { segment: 0, scheduling: inventory !== null ? "tags" : "none" },
+    }));
+    if (census.length === 0) {
+        // Both authorities refuse this: component-test-results/src/lib.rs
+        // `fold_jsonl` ("empty selection is a run error") and harness.mjs
+        // `runSuiteJsonl` ("suite enumerated zero cases").
+        throw new Error("suite enumerated zero cases (empty selection is a run error)");
+    }
+    const counts = { passed: 0, failed: 0, skipped: 0, na: 0, total: 0 };
+    for (const [i, testCase] of census.entries()) {
+        // Stripe membership (issue #110) is decided on the census index `i`,
+        // BEFORE `only`/tag filtering — a case outside this shard's stripe is
+        // skipped with no emit and no count contribution, as if this shard's
+        // census never enumerated it at all.
+        if (opts.shard && i % opts.shard.count !== opts.shard.index)
+            continue;
+        const name = String(await testCase.name());
+        counts.total++;
+        // js/viewer/harness.mjs `runCases`: "if (only && !name.includes(only))
+        // continue" — a filtered-out case is skipped entirely, no emit.
+        if (opts.only && !name.includes(opts.only))
+            continue;
+        // harness.mjs `runCases` mark scheduling, in its exact order: `only`
+        // first (above), then drift, then applicability. The N/A row's shape is
+        // the embed runner's (expected/verify-pipeline-fixture.jsonl):
+        // status, first excluding mark as detail, diagnostics-complete true.
+        if (inventory !== null) {
+            const tags = tagsOf(inventory, name);
+            if (tags === undefined) {
+                throw new Error(`inventory drift: no tags record covers ${name}`);
+            }
+            if (!applies(tags, missing)) {
+                counts.na++;
+                opts.emit(JSON.stringify({
+                    case: name,
+                    status: "not-applicable",
+                    detail: firstExcluding(tags, missing),
+                    "diagnostics-complete": true,
+                }), i);
+                opts.log?.(`${name} … not-applicable`);
+                continue;
+            }
+        }
+        // js/viewer/harness.mjs `runCases`' `freshCases` branch: re-enumerate
+        // from a fresh instance and run the matching case; a vanished case is
+        // inventory drift, not a failing case, and throws.
+        let executed = testCase;
+        if (freshCases) {
+            const freshTests = await newTests();
+            const freshList = await freshTests.all();
+            const match = await findByName(freshList, name, i);
+            if (match === undefined) {
+                throw new Error(`case '${name}' vanished on re-enumeration`);
+            }
+            executed = match;
+        }
+        const diags = [];
+        // The host-side `test-context` sideband: `diagnostic` calls are consumed
+        // concurrently with `run` per wit/tests.wit's doc comment — here that is
+        // automatic (same event loop turn, synchronous push into `diags`).
+        const ctx = new Context((msg) => diags.push(msg));
+        const start = performance.now();
+        // deno-lint-ignore no-explicit-any
+        let event;
+        try {
+            const attempt = executed.run(ctx);
+            let timedOut = false;
+            if (opts.caseTimeoutMs) {
+                let timer;
+                timedOut = await Promise.race([
+                    attempt.then(() => false),
+                    new Promise((resolve) => {
+                        timer = setTimeout(() => resolve(true), opts.caseTimeoutMs);
+                    }),
+                ]).finally(() => clearTimeout(timer));
+            }
+            else {
+                await attempt;
+            }
+            const durationMs = Math.round(performance.now() - start);
+            if (timedOut) {
+                counts.failed++;
+                event = {
+                    case: name,
+                    status: "fail",
+                    provenance: { "limit-exceeded": "case-timeout" },
+                    detail: `case timeout exceeded (${(opts.caseTimeoutMs / 1000)}s)`,
+                    "duration-ms": durationMs,
+                    "diagnostics-complete": false,
+                };
+            }
+            else {
+                counts.passed++;
+                event = {
+                    case: name,
+                    status: "pass",
+                    provenance: "returned",
+                    "duration-ms": durationMs,
+                    // The case returned normally, so its diagnostics sideband is
+                    // complete (upstream emits this on every returned row; polyengine's
+                    // trap/timeout rows already carry `false`).
+                    "diagnostics-complete": true,
+                };
+            }
+        }
+        catch (e) {
+            const durationMs = Math.round(performance.now() - start);
+            if (e instanceof ComponentException) {
+                const payload = e.payload;
+                if (payload?.kind === "failed") {
+                    counts.failed++;
+                    event = {
+                        case: name,
+                        status: "fail",
+                        provenance: "returned",
+                        detail: payload.value,
+                        "duration-ms": durationMs,
+                        "diagnostics-complete": true,
+                    };
+                }
+                else if (payload?.kind === "skipped") {
+                    counts.skipped++;
+                    event = {
+                        case: name,
+                        status: "skipped",
+                        provenance: "returned",
+                        detail: payload.value,
+                        "duration-ms": durationMs,
+                        "diagnostics-complete": true,
+                    };
+                }
+                else {
+                    // Contract violation: `outcome` has exactly two cases. Treat as
+                    // this case's failure, same as a trap (the run() promise made a
+                    // verdict-shaped claim the runner cannot parse).
+                    counts.failed++;
+                    event = {
+                        case: name,
+                        status: "fail",
+                        provenance: "trap",
+                        detail: `run() rejected with an unrecognized outcome payload: ` +
+                            `${JSON.stringify(payload)}`,
+                        "duration-ms": durationMs,
+                        "diagnostics-complete": false,
+                    };
+                }
+            }
+            else {
+                // Trap (real wasm trap, or any unbranded throw): "a runner treats a
+                // trap as this case's failure and the suite instance as poisoned"
+                // (wit/tests.wit `test-case.run` doc comment) — poisoning is moot
+                // under `freshCases` (the default), since the NEXT case gets a fresh
+                // instance regardless.
+                counts.failed++;
+                const isTrap = e instanceof Trap;
+                event = {
+                    case: name,
+                    status: "fail",
+                    provenance: "trap",
+                    detail: `trap: ${isTrap ? e.message : describeThrow(e)}`,
+                    "duration-ms": durationMs,
+                    "diagnostics-complete": false,
+                };
+            }
+        }
+        if (diags.length > 0)
+            event.diagnostics = diags;
+        opts.emit(JSON.stringify(event), i);
+        opts.log?.(`${name} … ${event.status}`);
+    }
+    opts.emit('{"segment-end":true}');
+    return counts;
+}
+// deno-lint-ignore no-explicit-any
+async function findByName(list, name, hint) {
+    // Same-index fast path. Enumeration order is a hint, not a contract: real
+    // suites enumerate deterministically, so the re-enumerated case is
+    // virtually always at its census index — one name() round-trip instead of
+    // a front-to-back scan. The scan (harness.mjs's freshCases branch, which
+    // the fallback below mirrors verbatim) is quadratic in suite size, and
+    // each name() here is an interpreted CABI call (~8 us): a 19k-case suite
+    // pays ~182M of them, dominating the run's wall clock. An order-unstable
+    // suite just misses the hint and falls back; drift detection is unchanged
+    // (`undefined` still means the case vanished).
+    if (hint !== undefined && hint < list.length) {
+        const candidate = list[hint];
+        if (String(await candidate.name()) === name)
+            return candidate;
+    }
+    for (const c of list) {
+        if (String(await c.name()) === name)
+            return c;
+    }
+    return undefined;
+}
+export { analyzeImports, MissingImportsError, requireImportsResolved } from "./import-analysis.js";

package/esm/tags.js

@@ -0,0 +1,164 @@
+// Feature-tag scheduling (issue #25): the L0 tags inventory and the
+// applicability rule, ported from polymorph-test's authorities —
+//
+//   - Section format: crates/component-test-formats/src/inventory.rs
+//     (`collect_tags_sections` / `parse_tags_records`): newline-delimited
+//     `name tag...` text records in `component-test:tags@0.1` custom
+//     sections, collected from the component AND nested modules/components
+//     (their reader uses wasmparser's `parse_all`, which descends; the
+//     SDK's `#[link_section]` puts the records in the guest CORE module,
+//     and those survive wac composition — verified empirically on the
+//     polymorph-tls composed suites). Records are newline-delimited within
+//     a section; a producer may omit the final newline, so a newline is
+//     repaired per section before concatenation, exactly as upstream does.
+//   - Record forms: `name tag...` (exact) and `prefix/* tag...` (generated
+//     rows: leaves are enumerated at run time below the prefix).
+//   - Applicability: crates/component-test-core/src/tags.rs — `feature`
+//     requires the target to HAVE the feature, `!feature` requires it to
+//     LACK it; a case applies iff every mark is satisfied against the
+//     runner's missing-features list. js/viewer/harness.mjs `applies()` is
+//     the JS-leg reference this mirrors.
+//   - Drift policy: harness.mjs `runCases` — an enumerated case that no
+//     record covers throws (the run is unsound, not failing).
+/** The custom-section name (component-test-core `name::TAGS_SECTION`). */
+export const TAGS_SECTION = "component-test:tags@0.1";
+const MAGIC = [0x00, 0x61, 0x73, 0x6d]; // "\0asm"
+function hasWasmMagic(bytes, at = 0) {
+    return bytes.length >= at + 8 && MAGIC.every((b, i) => bytes[at + i] === b);
+}
+/** u32 LEB128 at `pos`; returns [value, nextPos]. Traps on overlong/EOF. */
+function lebU32(bytes, pos) {
+    let result = 0;
+    let shift = 0;
+    for (;;) {
+        if (pos >= bytes.length)
+            throw new Error("tags scan: truncated LEB128");
+        const b = bytes[pos++];
+        result |= (b & 0x7f) << shift;
+        if ((b & 0x80) === 0)
+            break;
+        shift += 7;
+        if (shift >= 35)
+            throw new Error("tags scan: LEB128 too long for u32");
+    }
+    return [result >>> 0, pos];
+}
+/**
+ * Collect the concatenated bytes of every `component-test:tags@0.1` custom
+ * section in `bytes` — the component's own sections plus those of nested
+ * core modules (section id 1) and nested components (section id 4), which
+ * both embed complete wasm binaries. Returns null when no section exists
+ * anywhere (a suite not built with their SDK).
+ */
+export function collectTagsSections(bytes) {
+    if (!hasWasmMagic(bytes))
+        throw new Error("tags scan: not a wasm binary");
+    const chunks = [];
+    const decoder = new TextDecoder();
+    const NL = new Uint8Array([0x0a]);
+    const scan = (buf, core) => {
+        let pos = 8; // magic + version/layer
+        while (pos < buf.length) {
+            const id = buf[pos++];
+            const [size, afterSize] = lebU32(buf, pos);
+            pos = afterSize;
+            const end = pos + size;
+            if (end > buf.length)
+                throw new Error("tags scan: truncated section");
+            if (id === 0) {
+                const [nameLen, afterName] = lebU32(buf, pos);
+                const nameEnd = afterName + nameLen;
+                if (nameEnd > end)
+                    throw new Error("tags scan: truncated custom name");
+                if (decoder.decode(buf.subarray(afterName, nameEnd)) === TAGS_SECTION) {
+                    const data = buf.subarray(nameEnd, end);
+                    chunks.push(data);
+                    // Newline repair per section (inventory.rs: nothing guarantees a
+                    // producer terminates its last record).
+                    if (data.length === 0 || data[data.length - 1] !== 0x0a) {
+                        chunks.push(NL);
+                    }
+                }
+            }
+            else if (!core && (id === 1 || id === 4)) {
+                // 1 = core module, 4 = nested component: payload is a full binary.
+                const payload = buf.subarray(pos, end);
+                if (hasWasmMagic(payload))
+                    scan(payload, id === 1);
+            }
+            pos = end;
+        }
+    };
+    scan(bytes, false);
+    if (chunks.length === 0)
+        return null;
+    const total = chunks.reduce((n, c) => n + c.length, 0);
+    const out = new Uint8Array(total);
+    let off = 0;
+    for (const c of chunks) {
+        out.set(c, off);
+        off += c.length;
+    }
+    return out;
+}
+/**
+ * Parse concatenated records (inventory.rs `parse_tags_records`): one
+ * record per line, `name tag...`, blank lines skipped, duplicate names and
+ * empty tags rejected. Grammar validation beyond that (WIT-label checks)
+ * is the producer's job — their SDK validates at macro-expansion time.
+ */
+export function parseTagsRecords(bytes) {
+    const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    const inv = { exact: new Map(), prefixes: [] };
+    const seen = new Set();
+    for (const line of text.split("\n")) {
+        if (line.trim() === "")
+            continue;
+        const parts = line.split(" ").filter((p) => p !== "");
+        const name = parts[0];
+        const tags = parts.slice(1);
+        for (const t of tags) {
+            if (t === "" || t === "!") {
+                throw new Error(`tags section: empty mark on \`${name}\``);
+            }
+        }
+        if (seen.has(name)) {
+            throw new Error(`tags section: duplicate record \`${name}\``);
+        }
+        seen.add(name);
+        const prefix = name.endsWith("/*") ? name.slice(0, -2) : null;
+        if (prefix !== null) {
+            inv.prefixes.push({ prefix, tags });
+        }
+        else {
+            inv.exact.set(name, tags);
+        }
+    }
+    return inv;
+}
+/** Convenience: scan + parse; null when the suite carries no inventory. */
+export function loadTagsInventory(bytes) {
+    const sections = collectTagsSections(bytes);
+    return sections === null ? null : parseTagsRecords(sections);
+}
+/** The tags covering `name`: exact record, else a generated-row prefix
+ * record (leaves live below `prefix/`), else undefined (inventory drift). */
+export function tagsOf(inv, name) {
+    const exact = inv.exact.get(name);
+    if (exact !== undefined)
+        return exact;
+    for (const { prefix, tags } of inv.prefixes) {
+        if (name.startsWith(prefix + "/"))
+            return tags;
+    }
+    return undefined;
+}
+/** harness.mjs `applies()`: `!f` needs f missing; `f` needs f present. */
+export function applies(tags, missing) {
+    return tags.every((t) => t.startsWith("!") ? missing.includes(t.slice(1)) : !missing.includes(t));
+}
+/** The N/A row's `detail`: the first unsatisfied mark (harness.mjs's
+ * `excluding`), empty string if somehow none (mirrors `excluding ?? ""`). */
+export function firstExcluding(tags, missing) {
+    return tags.find((t) => t.startsWith("!") ? !missing.includes(t.slice(1)) : missing.includes(t)) ?? "";
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@polyengine/ct-runner",
+  "version": "0.1.0-pre.g633468a",
+  "description": "The polyengine execution runner for component-test-results (L1) conformance suites.",
+  "homepage": "https://github.com/polymorph-components/polyengine#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/polymorph-components/polyengine.git"
+  },
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/polymorph-components/polyengine/issues"
+  },
+  "module": "./esm/mod.js",
+  "types": "./types/mod.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./types/mod.d.ts",
+        "default": "./esm/mod.js"
+      }
+    },
+    "./context": {
+      "import": {
+        "types": "./types/context.d.ts",
+        "default": "./esm/context.js"
+      }
+    },
+    "./imports": {
+      "import": {
+        "types": "./types/import-analysis.d.ts",
+        "default": "./esm/import-analysis.js"
+      }
+    },
+    "./run": {
+      "import": {
+        "types": "./types/run-suite.d.ts",
+        "default": "./esm/run-suite.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {},
+  "type": "module",
+  "engines": {
+    "node": ">=22.14.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@polyengine/runtime": "0.1.0-pre.g633468a"
+  },
+  "_generatedBy": "dnt@0.43.2"
+}

package/types/context.d.ts

@@ -0,0 +1,28 @@
+/** The frozen L1 interface id `test-context` is provided under. */
+export declare const TEST_CONTEXT_INTERFACE = "polymorph:test/test-context@0.1.0";
+/**
+ * One case's diagnostic sink. Host-side: no reps, no side tables — see
+ * contracts/embedder-api.md's host-implemented-resource column.
+ *
+ * `diagnostic` "may block cooperatively" per the WIT doc comment; this
+ * in-process host implementation never blocks (no backpressure to model),
+ * so it resolves immediately — still a valid `async func` implementation
+ * (contracts/embedder-api.md: "sync implementations remain legal").
+ */
+export declare class Context {
+    #private;
+    constructor(onDiagnostic: (msg: string) => void);
+    diagnostic(msg: string): Promise<void>;
+}
+/**
+ * Build the `test-context` import-record entry
+ * (`{ [TEST_CONTEXT_INTERFACE]: { Context } }`), per contracts/embedder-api.md
+ * §"Module wiring and instantiation" (resource classes sit at the resource's
+ * position in the record, PascalCase).
+ *
+ * The class is registered once per `instantiate` call regardless of how many
+ * cases run against that instance; the runner never asks the guest to
+ * construct a `context` (the WIT resource has no constructor — the host
+ * always initiates the borrow itself when calling `run`).
+ */
+export declare function testContextImportRecord(): Record<string, unknown>;

package/types/import-analysis.d.ts

@@ -0,0 +1,35 @@
+import { type ImportLeaf, type PlanLike } from "@polyengine/runtime/embedder";
+/** One or more of the suite's import leaves cannot be resolved (yet). */
+export declare class MissingImportsError extends Error {
+    /** The unresolved leaves, in `requiredImports()` order. */
+    readonly leaves: ImportLeaf[];
+    /** The distinct top-level record keys (interface ids / bare names) missing. */
+    readonly missing: string[];
+    constructor(missing: string[], leaves: ImportLeaf[]);
+}
+export interface ImportAnalysis {
+    /** Every linkable import leaf (`requiredImports()`, unfiltered). */
+    leaves: ImportLeaf[];
+    /** Whether this suite imports `test-context` at all (world-shaped suites do;
+     * a pre-composed bundle with the provider already linked in does not). */
+    requiresTestContext: boolean;
+    /** Top-level keys the suite needs that `provided` (plus test-context, if
+     * this runner will supply it) does not resolve. Empty when runnable. */
+    missing: string[];
+}
+/**
+ * Analyze a suite's import surface against a caller-provided imports record,
+ * WITHOUT instantiating anything (translate-only; `requiredImports` reads
+ * only the plan). Detects:
+ *  - whether `test-context` is imported (only then does the runner provide
+ *    it — pre-composed bundles with the provider already linked must work
+ *    too, per the dispatch);
+ *  - a caller/runner collision on `test-context` (the runner "merges,
+ *    erroring on collisions" per the dispatch's import-wiring spec);
+ *  - every other top-level import key the suite needs but `provided` lacks,
+ *    via the same version-canonical resolution `instantiate` itself uses
+ *    (`ImportResolver`, contracts/embedder-api.md §"Version canonicalization").
+ */
+export declare function analyzeImports(plan: PlanLike, provided?: Record<string, unknown>): ImportAnalysis;
+/** `analyzeImports`, throwing `MissingImportsError` if anything is missing. */
+export declare function requireImportsResolved(plan: PlanLike, provided?: Record<string, unknown>): ImportAnalysis;

package/types/mod.d.ts

@@ -0,0 +1,4 @@
+export { type RunCounts, runSuite, type RunSuiteOptions, TESTS_INTERFACE, } from "./run-suite.js";
+export { analyzeImports, type ImportAnalysis, MissingImportsError, requireImportsResolved, } from "./import-analysis.js";
+export { Context, TEST_CONTEXT_INTERFACE, testContextImportRecord } from "./context.js";
+export { applies, collectTagsSections, firstExcluding, loadTagsInventory, parseTagsRecords, TAGS_SECTION, type TagsInventory, tagsOf, } from "./tags.js";

package/types/run-suite.d.ts

@@ -0,0 +1,117 @@
+import { type ComponentArtifacts } from "@polyengine/runtime/embedder";
+/** The suite's `tests` interface id (wit/tests.wit `interface tests`, v0.1.0). */
+export declare const TESTS_INTERFACE = "polymorph:test/tests@0.1.0";
+export interface RunSuiteOptions {
+    /**
+     * Host imports for everything the suite needs OTHER than test-context
+     * (WASI, SUT interfaces, …) — the same shape `instantiate` itself takes
+     * (contracts/embedder-api.md §"Module wiring and instantiation"). The
+     * runner adds `test-context` itself and errors on a collision (dispatch's
+     * import-wiring spec); omit it here.
+     */
+    imports?: Record<string, unknown>;
+    /** Envelope `target` (opaque implementation x environment key). */
+    target: string;
+    /**
+     * Envelope `suite.name`. Per js/viewer/harness.mjs's `envelope()`: "the
+     * suite name is normalized to the lockfile identity — the wasm file stem,
+     * underscores"; callers may pass the kebab-case name as-is, this function
+     * does the same normalization (`replaceAll("-", "_")`).
+     */
+    suiteName: string;
+    /** Substring filter: non-matching cases are skipped entirely (no emit),
+     * per js/viewer/harness.mjs `runCases`'s `only` handling. */
+    only?: string;
+    /**
+     * Feature-tag scheduling (issue #25): the features this target LACKS —
+     * js/viewer/harness.mjs's `missing`. Tag-gating activates whenever the
+     * suite carries a `component-test:tags@0.1` inventory (src/tags.ts):
+     * non-applicable cases emit `not-applicable` rows instead of executing,
+     * and an enumerated case no record covers throws (inventory drift — the
+     * run is unsound, not failing). Passing `missing` for a suite WITHOUT an
+     * inventory is an error (gating requested but impossible — upstream's
+     * runner refuses the same way rather than silently degrading).
+     */
+    missing?: string[];
+    /**
+     * Per-case wall-clock budget in ms (the `--case-timeout` runner option
+     * documented in harness.mjs's `runSuiteJsonl` doc comment). On expiry the
+     * case fails with `{"limit-exceeded":"case-timeout"}` provenance and the
+     * loop moves on; JSPI attempts cannot be cancelled, so this is only safe
+     * paired with `freshCases` (the default) — see below.
+     */
+    caseTimeoutMs?: number;
+    /**
+     * Fresh suite instance per case (default true). harness.mjs's doc comment
+     * on `runSuiteJsonl`'s `freshCases` parameter: "a fresh instance per case
+     * ... contains trap poisoning" and is required to pair with
+     * `caseTimeoutMs` (an abandoned JSPI attempt keeps running until its
+     * instance is dropped). Setting this false reuses one instance for the
+     * whole run — legal, but a trapped case can poison every later one, exactly
+     * as harness.mjs warns.
+     */
+    freshCases?: boolean;
+    /** Opt in to JSPI-backed suspension; passed through to `instantiate`. */
+    jspi?: boolean;
+    /**
+     * Stripe this run to one shard of the suite (issue #110): case `i`
+     * (i = the census index — `census.entries()`'s index over the FULL
+     * enumerated case list, before `only`/tag filtering) belongs to shard
+     * `i % count`; this shard executes and emits only its own cases, mirroring
+     * `runCases`' established `i % count === index` striping semantics
+     * (striping, not contiguous ranges, balances load since expensive cases
+     * cluster by group). `only`/tag-gating are applied AFTER stripe
+     * membership is decided (a case not in this stripe is neither executed
+     * nor emitted, exactly as if it never existed for this shard) — this is
+     * the interpretation that keeps the invariant "the union of every shard's
+     * rows, in suite order, equals the unsharded run's rows" (pinned by
+     * shard_test.ts's partition-identity test).
+     *
+     * Sharded envelope/terminator contract: a sharded call still emits its
+     * own envelope line and its own `{"segment-end":true}` terminator —
+     * `runSuite` does not know about sibling shards and cannot merge. The
+     * documented consumer topology (issue #110's stated shape) is: a
+     * caller-side worker pool runs one `runSuite` call per shard, and the
+     * PARENT — not this function — discards all but one envelope, merges the
+     * per-case rows back into suite order using the `index` argument now
+     * passed to `emit`, and writes the single terminator. The returned
+     * `RunCounts` are likewise per-shard (they count only this stripe's
+     * cases); the parent sums them. `shard` absent
+     * (the default) is byte-identical to today: no `index` shard-partitioning
+     * occurs and single-argument `emit` callers are unaffected.
+     */
+    shard?: {
+        index: number;
+        count: number;
+    };
+    /** Receives each output line (envelope, one per case, terminator),
+     * WITHOUT a trailing newline — callers decide the line separator.
+     * `caseIndex` (issue #110) is the case's suite-order index (the same `i`
+     * used for stripe membership) for per-case rows; `undefined` for the
+     * envelope and terminator lines. A sharded consumer uses it to restore
+     * suite order when merging stripes back together. Optional second
+     * argument: existing single-argument `emit` callers are unaffected. */
+    emit: (line: string, caseIndex?: number) => void;
+    /** Optional progress log, one call per case (mirrors harness.mjs's
+     * `log?.(...)` callback). */
+    log?: (msg: string) => void;
+}
+export interface RunCounts {
+    passed: number;
+    failed: number;
+    skipped: number;
+    /** Cases scheduled out as `not-applicable` (tag gating; harness.mjs `na`). */
+    na: number;
+    total: number;
+}
+/**
+ * Run one suite end to end: instantiate, enumerate, execute every case,
+ * emit the complete results-JSONL stream (envelope, one line per case,
+ * terminator) through `opts.emit`. Throws `MissingImportsError` up front
+ * (contracts/embedder-api.md's `requiredImports`) if the caller's imports
+ * cannot satisfy the suite, and a plain `Error` if the census is empty (an
+ * empty selection is a run error, per component-test-results/src/lib.rs's
+ * `fold_jsonl` and harness.mjs's `runSuiteJsonl` — both refuse it).
+ */
+export declare function runSuite(artifacts: ComponentArtifacts, opts: RunSuiteOptions): Promise<RunCounts>;
+export { analyzeImports, MissingImportsError, requireImportsResolved } from "./import-analysis.js";

package/types/tags.d.ts

@@ -0,0 +1,35 @@
+/** The custom-section name (component-test-core `name::TAGS_SECTION`). */
+export declare const TAGS_SECTION = "component-test:tags@0.1";
+/** Parsed static inventory: exact case records + generated-row prefixes. */
+export interface TagsInventory {
+    exact: Map<string, string[]>;
+    prefixes: Array<{
+        prefix: string;
+        tags: string[];
+    }>;
+}
+/**
+ * Collect the concatenated bytes of every `component-test:tags@0.1` custom
+ * section in `bytes` — the component's own sections plus those of nested
+ * core modules (section id 1) and nested components (section id 4), which
+ * both embed complete wasm binaries. Returns null when no section exists
+ * anywhere (a suite not built with their SDK).
+ */
+export declare function collectTagsSections(bytes: Uint8Array): Uint8Array | null;
+/**
+ * Parse concatenated records (inventory.rs `parse_tags_records`): one
+ * record per line, `name tag...`, blank lines skipped, duplicate names and
+ * empty tags rejected. Grammar validation beyond that (WIT-label checks)
+ * is the producer's job — their SDK validates at macro-expansion time.
+ */
+export declare function parseTagsRecords(bytes: Uint8Array): TagsInventory;
+/** Convenience: scan + parse; null when the suite carries no inventory. */
+export declare function loadTagsInventory(bytes: Uint8Array): TagsInventory | null;
+/** The tags covering `name`: exact record, else a generated-row prefix
+ * record (leaves live below `prefix/`), else undefined (inventory drift). */
+export declare function tagsOf(inv: TagsInventory, name: string): string[] | undefined;
+/** harness.mjs `applies()`: `!f` needs f missing; `f` needs f present. */
+export declare function applies(tags: string[], missing: string[]): boolean;
+/** The N/A row's `detail`: the first unsatisfied mark (harness.mjs's
+ * `excluding`), empty string if somehow none (mirrors `excluding ?? ""`). */
+export declare function firstExcluding(tags: string[], missing: string[]): string;