@polyengine/ct-runner 0.1.0-pre.g633468a → 0.2.0-pre.g20030fc

package/README.md

@@ -15,7 +15,7 @@ npm install @polyengine/ct-runner
 import * as api from "@polyengine/ct-runner";
 ```
 
-Entry points: `.`, `./context`, `./imports`, `./run`.
+Entry points: `.`, `./imports`, `./run`.
 
 ESM only, Node >= 22.14. Documentation, examples and the embedder API contract
 live in the [repository](https://github.com/polymorph-components/polyengine).

package/esm/context.js

@@ -11,7 +11,12 @@
 // 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. */
+/**
+ * The frozen L1 interface id `test-context` is provided under.
+ *
+ * @internal — test-only export; wired automatically by `runSuite()`, which
+ * is the public entry point. No caller supplies or overrides this key.
+ */
 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
@@ -21,6 +26,9 @@ export const TEST_CONTEXT_INTERFACE = "polymorph:test/test-context@0.1.0";
  * 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").
+ *
+ * @internal — constructed only by `runSuite()`'s internal wiring; no
+ * `RunSuiteOptions` field accepts or overrides a `Context` instance.
  */
 export class Context {
     #onDiagnostic;
@@ -42,6 +50,9 @@ export class Context {
  * 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`).
+ *
+ * @internal — called only by `runSuite()`'s internal import-merging; the
+ * public entry point is `runSuite()` itself.
  */
 export function testContextImportRecord() {
     return { [TEST_CONTEXT_INTERFACE]: { Context } };

package/esm/run-suite.js

@@ -14,7 +14,13 @@ import { instantiate, Trap, ComponentException, } from "@polyengine/runtime/embe
 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). */
+/**
+ * The suite's `tests` interface id (wit/tests.wit `interface tests`, v0.1.0).
+ *
+ * @internal — used only inside this module's export lookup; no importer
+ * (including this package's own tests) references it. The public entry
+ * point is `runSuite()`.
+ */
 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

package/esm/tags.js

@@ -20,7 +20,12 @@
 //     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`). */
+/**
+ * The custom-section name (component-test-core `name::TAGS_SECTION`).
+ *
+ * @internal — test-only export; wired automatically by `runSuite()`'s tag
+ * scheduling, the public entry point.
+ */
 export const TAGS_SECTION = "component-test:tags@0.1";
 const MAGIC = [0x00, 0x61, 0x73, 0x6d]; // "\0asm"
 function hasWasmMagic(bytes, at = 0) {
@@ -49,6 +54,10 @@ function lebU32(bytes, pos) {
  * 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).
+ *
+ * @internal — used only by `loadTagsInventory()` and this package's own
+ * tests; the public entry point is `runSuite()`, which schedules tag
+ * gating automatically.
  */
 export function collectTagsSections(bytes) {
     if (!hasWasmMagic(bytes))
@@ -106,6 +115,9 @@ export function collectTagsSections(bytes) {
  * 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.
+ *
+ * @internal — used only by `loadTagsInventory()` and this package's own
+ * tests; the public entry point is `runSuite()`.
  */
 export function parseTagsRecords(bytes) {
     const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
@@ -136,13 +148,21 @@ export function parseTagsRecords(bytes) {
     }
     return inv;
 }
-/** Convenience: scan + parse; null when the suite carries no inventory. */
+/**
+ * Convenience: scan + parse; null when the suite carries no inventory.
+ *
+ * @internal — used only by `run-suite.ts`'s automatic tag scheduling and
+ * this package's own tests; the public entry point is `runSuite()`.
+ */
 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). */
+ * record (leaves live below `prefix/`), else undefined (inventory drift).
+ *
+ * @internal — used only by `run-suite.ts`'s per-case scheduling and this
+ * package's own tests; the public entry point is `runSuite()`. */
 export function tagsOf(inv, name) {
     const exact = inv.exact.get(name);
     if (exact !== undefined)
@@ -153,12 +173,18 @@ export function tagsOf(inv, name) {
     }
     return undefined;
 }
-/** harness.mjs `applies()`: `!f` needs f missing; `f` needs f present. */
+/** harness.mjs `applies()`: `!f` needs f missing; `f` needs f present.
+ *
+ * @internal — used only by `run-suite.ts`'s scheduling and this package's
+ * own tests; the public entry point is `runSuite()`. */
 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 ?? ""`). */
+ * `excluding`), empty string if somehow none (mirrors `excluding ?? ""`).
+ *
+ * @internal — used only by `run-suite.ts`'s scheduling and this package's
+ * own tests; the public entry point is `runSuite()`. */
 export function firstExcluding(tags, missing) {
     return tags.find((t) => t.startsWith("!") ? !missing.includes(t.slice(1)) : missing.includes(t)) ?? "";
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polyengine/ct-runner",
-  "version": "0.1.0-pre.g633468a",
+  "version": "0.2.0-pre.g20030fc",
   "description": "The polyengine execution runner for component-test-results (L1) conformance suites.",
   "homepage": "https://github.com/polymorph-components/polyengine#readme",
   "repository": {
@@ -20,12 +20,6 @@
         "default": "./esm/mod.js"
       }
     },
-    "./context": {
-      "import": {
-        "types": "./types/context.d.ts",
-        "default": "./esm/context.js"
-      }
-    },
     "./imports": {
       "import": {
         "types": "./types/import-analysis.d.ts",
@@ -49,7 +43,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@polyengine/runtime": "0.1.0-pre.g633468a"
+    "@polyengine/runtime": "0.2.0-pre.g20030fc"
   },
   "_generatedBy": "dnt@0.43.2"
 }

package/types/context.d.ts

@@ -1,4 +1,9 @@
-/** The frozen L1 interface id `test-context` is provided under. */
+/**
+ * The frozen L1 interface id `test-context` is provided under.
+ *
+ * @internal — test-only export; wired automatically by `runSuite()`, which
+ * is the public entry point. No caller supplies or overrides this key.
+ */
 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
@@ -8,6 +13,9 @@ export declare const TEST_CONTEXT_INTERFACE = "polymorph:test/test-context@0.1.0
  * 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").
+ *
+ * @internal — constructed only by `runSuite()`'s internal wiring; no
+ * `RunSuiteOptions` field accepts or overrides a `Context` instance.
  */
 export declare class Context {
     #private;
@@ -24,5 +32,8 @@ export declare class Context {
  * 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`).
+ *
+ * @internal — called only by `runSuite()`'s internal import-merging; the
+ * public entry point is `runSuite()` itself.
  */
 export declare function testContextImportRecord(): Record<string, unknown>;

package/types/run-suite.d.ts

@@ -1,5 +1,11 @@
 import { type ComponentArtifacts } from "@polyengine/runtime/embedder";
-/** The suite's `tests` interface id (wit/tests.wit `interface tests`, v0.1.0). */
+/**
+ * The suite's `tests` interface id (wit/tests.wit `interface tests`, v0.1.0).
+ *
+ * @internal — used only inside this module's export lookup; no importer
+ * (including this package's own tests) references it. The public entry
+ * point is `runSuite()`.
+ */
 export declare const TESTS_INTERFACE = "polymorph:test/tests@0.1.0";
 export interface RunSuiteOptions {
     /**

package/types/tags.d.ts

@@ -1,6 +1,17 @@
-/** The custom-section name (component-test-core `name::TAGS_SECTION`). */
+/**
+ * The custom-section name (component-test-core `name::TAGS_SECTION`).
+ *
+ * @internal — test-only export; wired automatically by `runSuite()`'s tag
+ * scheduling, the public entry point.
+ */
 export declare const TAGS_SECTION = "component-test:tags@0.1";
-/** Parsed static inventory: exact case records + generated-row prefixes. */
+/**
+ * Parsed static inventory: exact case records + generated-row prefixes.
+ *
+ * @internal — an internal shape passed between this module's own
+ * functions and `run-suite.ts`; not part of `runSuite()`'s public
+ * options/return shape.
+ */
 export interface TagsInventory {
     exact: Map<string, string[]>;
     prefixes: Array<{
@@ -14,6 +25,10 @@ export interface TagsInventory {
  * 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).
+ *
+ * @internal — used only by `loadTagsInventory()` and this package's own
+ * tests; the public entry point is `runSuite()`, which schedules tag
+ * gating automatically.
  */
 export declare function collectTagsSections(bytes: Uint8Array): Uint8Array | null;
 /**
@@ -21,15 +36,32 @@ export declare function collectTagsSections(bytes: Uint8Array): Uint8Array | nul
  * 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.
+ *
+ * @internal — used only by `loadTagsInventory()` and this package's own
+ * tests; the public entry point is `runSuite()`.
  */
 export declare function parseTagsRecords(bytes: Uint8Array): TagsInventory;
-/** Convenience: scan + parse; null when the suite carries no inventory. */
+/**
+ * Convenience: scan + parse; null when the suite carries no inventory.
+ *
+ * @internal — used only by `run-suite.ts`'s automatic tag scheduling and
+ * this package's own tests; the public entry point is `runSuite()`.
+ */
 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). */
+ * record (leaves live below `prefix/`), else undefined (inventory drift).
+ *
+ * @internal — used only by `run-suite.ts`'s per-case scheduling and this
+ * package's own tests; the public entry point is `runSuite()`. */
 export declare function tagsOf(inv: TagsInventory, name: string): string[] | undefined;
-/** harness.mjs `applies()`: `!f` needs f missing; `f` needs f present. */
+/** harness.mjs `applies()`: `!f` needs f missing; `f` needs f present.
+ *
+ * @internal — used only by `run-suite.ts`'s scheduling and this package's
+ * own tests; the public entry point is `runSuite()`. */
 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 ?? ""`). */
+ * `excluding`), empty string if somehow none (mirrors `excluding ?? ""`).
+ *
+ * @internal — used only by `run-suite.ts`'s scheduling and this package's
+ * own tests; the public entry point is `runSuite()`. */
 export declare function firstExcluding(tags: string[], missing: string[]): string;