@volter/twin-catalog 0.2.28 → 0.2.29

package/catalog.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "sourceCommit": "a6584aeee5b2761e628cb8a90b22bdf2c6862359",
+  "sourceCommit": "251b4771b7e0f8f262041cc47f436d8b4f785537",
   "digest": "3195c901d6068ef7be8e9e23676b9b6ec58fb4e50c2d5604bbea390fefec9fdb",
   "versions": [
     {

package/docs/contributing.md

@@ -5,7 +5,7 @@ not scripts from a platform checkout. Read the [process](process.md) for identit
 
 ## Build a pack
 
-Install Bun at the catalog policy's version and the public `@volter/world-core`, `@volter/world-runtime` and
+Install Bun at the catalog policy's version and the public `@volter/world`, `@volter/world-core`, `@volter/world-runtime` and
 `@volter/twin-standard` versions in `policy.json`. Install TypeScript and its Node/Bun types as development dependencies.
 Keep the package directory named for the vendor; its npm package name is independent.
 
@@ -14,7 +14,9 @@ bunx --bun twin-standard create stripe --init stripe --package @example/payments
 ```
 
 The generated files contain explicit fill markers. Author the vendored spec and its provenance, demand, manifest,
-stored resource states, decision table, handlers and customer journey in the standard's required order. The package
+stored resource states, decision table, handlers and customer journey in the standard's required order. Start the
+outline from the vendor quickstart and pinned SDK's ordinary default requests, app environment and issued identity.
+Walk that customer entry while building; reducing its requested fields to match the twin does not establish compatibility. The package
 README describes its vendor surface, refusals and limits. Declare your own public GitHub repository and license in
 package.json. Complete source requirements before derivation:
 
@@ -34,7 +36,27 @@ LICENSE. A build and `npm pack --dry-run` must show those paths; no platform-spe
 
 ## Assess before submitting
 
-Walk the life's journeys while implementing. For the final assessment, run the released standard through a World:
+Package the customer entry in `journeys/first-use.json`. It has `schemaVersion: 1`, the upstream `source`, an
+`about` describing its scope, and a `files` map of relative paths to text. Include `package.json` with exact registry
+SDK dependencies, `.env.example` with the names the app reads, and its unchanged client script with result
+assertions. `run` is an argument array such as `["node", "workflow.mjs"]`. For stored workflows,
+`retention: { "readback": ["node", "readback.mjs"] }` inspects prior state without creating it again. A stateless
+workflow instead declares `retention: { "none": "<why no stored vendor resource is created>" }`. Use SDKs to create
+stored data and existing vendor doors for synthetic setup; do not use scenario success in place of a stored write.
+The standard owns CLI lifecycle and teardown, so the scripts do not start or stop infrastructure themselves. For a timed workflow, `clock: { "at": "<ISO instant>", "advanceAfterRun": "10s" }` freezes time before the client runs, then advances and inspects the due result before retention is measured. The duration is the journey’s chosen synthetic wait, not a vendor timing guarantee.
+
+Walk the life's journeys and this first-use journey while implementing. For final qualification, build and pack
+first, install that tarball in a fresh directory without development links, and run the released standard against
+the installed package. Keep the archive inventory and lockfile. Prepare a new customer app beside that installation:
+
+```sh
+twin-standard prepare-consumer <installed pack dir> --app <new app dir> --cli <absolute installed volter executable> --integrity <packed SHA-512 integrity> --out prepared-consumer.json
+npm install --prefix <new app dir> --ignore-scripts --no-audit --no-fund
+```
+
+This preparation writes fixture files only; SDK dependency installation precedes offline execution. The product
+CLI must resolve the installed candidate through that app's parent dependency directory. For the final assessment,
+run the released standard through a World:
 
 Create `assessment.world.config.json`:
 
@@ -43,15 +65,16 @@ Create `assessment.world.config.json`:
 ```
 
 ```sh
-volter-world run assessment.world.config.json --root . --env-out /tmp/new-assessment.env --owner pack-assessment -- bunx --bun twin-standard assess stripe --browser --out assessment.json
+volter-world run assessment.world.config.json --root . --env-out /tmp/new-assessment.env --owner pack-assessment -- twin-standard assess <installed pack dir> --prepared-consumer prepared-consumer.json --browser --out assessment.json
 ```
 
-The assessment config has no vendor services; the standard creates fresh in-memory World state for each journey.
+The outer assessment config has no vendor services; the standard creates fresh in-memory state for journey replay
+and uses the product CLI to own a separate app World for the installed customer workflow.
 For an HTTP browser target, use Linux, install Playwright at the catalog policy version and its Chromium binary,
 and install `libfaketime` (Debian/Ubuntu: `sudo apt-get install libfaketime`). The browser process uses the World
 clock for native cookie expiry, at one-second precision; JavaScript time retains millisecond precision. Authors on
 other platforms can omit `--browser` for in-process assessment; catalog Actions supplies the browser target. The report
-separates declared served/gap counts, operations actually exercised, deterministic replay, conformance and Chromium
+separates declared served/gap counts, operations actually exercised, deterministic replay, conformance, installed customer workflow and Chromium
 results. It does not measure DOM interactions, line coverage, real-vendor parity or every possible state transition.
 
 Local assessment helps authors; it does not replace the independent catalog assessment of the published tarball.

package/docs/process.md

@@ -47,6 +47,8 @@ does not change that pin. Removing a recommendation is not uninstalling a runnin
 Each assessed release exposes its artifact's description, license, Node requirements, kernel peer requirements,
 source directory and issue tracker beside its integrity, provenance and measured behavior. README and license links
 point to the source commit verified by npm provenance. They describe that version, not the publisher's current branch.
+The JSON-only reader also projects installed customer scope, pinned SDK dependencies, actual CLI/kernel/runtime versions, clock conditions, retention and teardown when the bound report measured them. An older report exposes `consumer: null`; it cannot acquire a passing workflow from publisher trust or a later test.
+
 Historical assessments without these retained fields show them as unavailable; current registry metadata does not
 fill missing historical evidence. A provenance link establishes source and build identity, not vendor fidelity.
 
@@ -81,7 +83,8 @@ An already admitted package/version cannot acquire different bytes or a differen
 
 The catalog evaluates only the tarball fetched at the declared integrity. Package source in the contributor's
 repository and evidence supplied in the PR are context, never substitutes for running that artifact. A submission
-cannot select its own evaluator, thresholds, registry, commands or privileges.
+cannot select its own evaluator, thresholds, registry or privileges. A pack's customer fixture supplies its
+unchanged client invocation; the pinned standard owns initialization, lifecycle, assertions and readiness.
 
 ## State and invalidation
 
@@ -143,7 +146,8 @@ routing, not the isolation boundary: the container enforces the evaluation netwo
 The trusted controller owns success/failure, hashes and run identity. Candidate output is untrusted data; bounded
 report parsing never executes it or interpolates it into a shell. It can explain results but cannot confer merge or
 publication authority. The trusted summary renderer escapes contributor strings and neutralizes mentions. Raw logs
-and JSON evidence are downloadable artifacts. There is no execution of arbitrary contributor-supplied test commands.
+and JSON evidence are downloadable artifacts. A packaged first-use fixture executes only in the offline assessment
+container under the same unprivileged boundary as the candidate pack; it has no controller or admission authority.
 Conformance and journey checks are the versioned standard's own entrypoints. Like any in-process plugin check, they
 measure cooperative pack behavior, not a proof that malicious executable code cannot deceive a test; moderator
 source review remains part of admission.
@@ -161,6 +165,21 @@ The released standard owns the development SDK versions used by its client cases
 The versioned `@volter/twin-standard` owns the checks and machine-readable assessment API. The catalog invokes it;
 it does not implement another Protocol 3 grader or journey engine. Evaluation occurs inside a task-owned World.
 
+Installed customer readiness is separate from the HTTP journey replay. The released standard materializes the
+pack's `journeys/first-use.json` in a new application directory; versioned standard fixtures cover older immutable
+artifacts that predate this format. Preparation installs the fixture's exact SDK versions with scripts disabled,
+retains its resolved dependency lock and recipe digest, and pins the product CLI alongside the kernel and runtime.
+Evaluation calls normal `volter world init` and checks that its service uses the exact candidate package/version,
+then runs the unchanged client and its result assertions. A stored workflow must retain its state through `down`
+and `up`; its readback may add no mutations. Timed workflows settle the declared result under an explicit frozen/advanced World clock before the retention baseline, so runtime scheduling delay is not a test input. A stateless workflow names why this does not apply. Final stopped
+status is required. Missing or failing consumer evidence means changes needed, even when source form and replay pass.
+These walks establish the advertised workflow at the recorded SDK and tool versions; they do not establish every
+SDK method, complete vendor parity or production delivery. Historical reports keep their original scope.
+
+The Linux runner installs native PostgreSQL tools without a distribution-owned cluster for customer workflows
+that declare that backing. Each World starts and stops its own database through the runtime; the container image
+and the tool/SDK locks identify the execution conditions.
+
 Quick assessment walks the packaged customer journey twice from fresh state with the same clock and World draws.
 It reports failures, answered steps, response replay equality, and served/gap counts over the entire declared surface. Actual operation coverage comes from kernel dispatch, with
 every declared gap retained in the denominator; declared support and exercised coverage are separate fields.

package/lib/browse.d.mts

@@ -7,6 +7,19 @@ export type Coverage = {
 };
 export type Replay = { equal: boolean; runs: number; firstSha256: string; secondSha256: string };
 export type Measurements = {
+  consumer: null | {
+    measured: boolean;
+    passed: boolean;
+    scope: string | null;
+    fixture: string | null;
+    sdkDependencies: Record<string, string> | null;
+    tools: Record<string, string> | null;
+    clock: Record<string, unknown> | null;
+    retainedReadback: boolean | null;
+    retentionNotApplicable: string | null;
+    teardownVerified: boolean | null;
+    failures: string[] | null;
+  };
   scope: string | null;
   surface: { total: number; served: number; gap: number } | null;
   operationCoverage: Coverage | null;

package/lib/browse.mjs

@@ -130,6 +130,16 @@ export function browse(root, { vendor, package: packageName, integrity = null }
                     operationCoverage: quick?.operationCoverage ?? null, servedOperations: quick?.servedOperations ?? null,
                     steps: quick?.steps ?? null, answered: quick?.answered ?? null, failures: quick?.failures ?? null,
                     replay: quick?.replay ?? null, conformance: bound.report.conformance ?? null,
+                    consumer: bound.report.consumer ? {
+                      measured: bound.report.consumer.measured === true, passed: bound.report.consumer.passed === true,
+                      scope: bound.report.consumer.scope ?? null, fixture: bound.report.consumer.fixture ?? null,
+                      sdkDependencies: bound.envelope.prepared?.consumerFixture?.dependencies ?? null,
+                      tools: bound.report.consumer.tools ?? null, clock: bound.report.consumer.clock ?? null,
+                      retainedReadback: bound.report.consumer.retainedReadback ?? null,
+                      retentionNotApplicable: bound.report.consumer.retentionNotApplicable ?? null,
+                      teardownVerified: bound.report.consumer.teardownVerified ?? null,
+                      failures: bound.report.consumer.failures ?? null,
+                    } : null,
                     browser: browser?.measured === true ? browser : null,
                     codeCoverage: quick?.codeCoverage ?? null, stateTransitionCoverage: quick?.stateTransitionCoverage ?? null,
                     domCoverage: browser?.domCoverage ?? null, comparison: bound.report.comparison ?? null } : null };

package/lib/runner.mjs

@@ -25,7 +25,8 @@ export function withContainer(root, input, output, execute, { spawn = spawnSync
   let volume = false;
   try {
     const tools = input.policy.tools;
-    run(['build', '--iidfile', imageFile, '--build-arg', `NODE_IMAGE=${input.policy.nodeImage}`, '--build-arg', `BUN_VERSION=${input.policy.bun}`, '--build-arg', `STANDARD_VERSION=${tools['@volter/twin-standard']}`, '--build-arg', `CORE_VERSION=${tools['@volter/world-core']}`, '--build-arg', `RUNTIME_VERSION=${tools['@volter/world-runtime']}`, '--build-arg', `PLAYWRIGHT_VERSION=${tools.playwright}`, '-f', join(root, 'runner/Dockerfile'), root]);
+    requireThat(tools['@volter/world'], 'policy must pin the product CLI for installed customer workflows');
+    run(['build', '--iidfile', imageFile, '--build-arg', `NODE_IMAGE=${input.policy.nodeImage}`, '--build-arg', `BUN_VERSION=${input.policy.bun}`, '--build-arg', `STANDARD_VERSION=${tools['@volter/twin-standard']}`, '--build-arg', `CORE_VERSION=${tools['@volter/world-core']}`, '--build-arg', `RUNTIME_VERSION=${tools['@volter/world-runtime']}`, '--build-arg', `CLI_VERSION=${tools['@volter/world']}`, '--build-arg', `PLAYWRIGHT_VERSION=${tools.playwright}`, '-f', join(root, 'runner/Dockerfile'), root]);
     const image = readFileSync(imageFile, 'utf8').trim();
     requireThat(/^sha256:[a-f0-9]{64}$/.test(image), 'container image has no immutable identity');
     run(['volume', 'create', '--label', `twin-catalog.owner=${id}`, '--label', `twin-catalog.run=${runOwner}`, id]); volume = true;
@@ -56,12 +57,15 @@ export function evaluate(root, input, output, options = {}) {
       const lock = run([...common, '--network', 'none', image, '-e', 'process.stdout.write(require("fs").readFileSync("/work/package-lock.json","utf8"))']).stdout;
       requireThat(digest(lock) === prepared.dependencyLockSha256, 'dependency lock identity changed');
       write(`${output}.lock.json`, JSON.parse(lock));
+      const consumerLock = run([...common, '--network', 'none', image, '-e', 'process.stdout.write(require("fs").readFileSync("/work/customer-app/package-lock.json","utf8"))']).stdout;
+      requireThat(digest(consumerLock) === prepared.consumerDependencyLockSha256, 'customer SDK lock identity changed');
+      write(`${output}.consumer-lock.json`, JSON.parse(consumerLock));
       phase = 'offline-assessment';
       const result = run([...common, '--network', 'none', '--entrypoint', 'bun', image, '/opt/catalog/node_modules/@volter/world-runtime/src/cli.ts', 'run', '/work/world.json', '--root', '/work', '--env-out', '/work/world.env', '--owner', owner, '--', 'bun', '/opt/catalog/runner/evaluate.mjs'], true);
       const reportRead = run([...common, '--network', 'none', image, '-e', 'process.stdout.write(require("fs").readFileSync("/work/report.json","utf8"))'], true);
       const report = reportRead.status === 0 ? JSON.parse(reportRead.stdout) : null;
       requireThat(!report || (report.schemaVersion === 1 && report.package === input.submission.package && report.version === input.submission.version && report.integrity === input.submission.integrity), 'evaluator returned a mismatched report');
-      const envelope = { schemaVersion: 1, inputSha256: digest(input), input, image, prepared, dependencyLock: JSON.parse(lock), status: result.status === 0 && report?.ready === true ? 'ready' : 'changes-needed', report, evaluatedAt: new Date().toISOString() };
+      const envelope = { schemaVersion: 1, inputSha256: digest(input), input, image, prepared, dependencyLock: JSON.parse(lock), consumerDependencyLock: JSON.parse(consumerLock), status: result.status === 0 && report?.ready === true ? 'ready' : 'changes-needed', report, evaluatedAt: new Date().toISOString() };
       write(output, envelope);
       return envelope;
     }, options);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/twin-catalog",
-  "version": "0.2.28",
+  "version": "0.2.29",
   "description": "The moderated twin distribution: approved versions and submission tooling for independent publishers.",
   "type": "module",
   "bin": {
@@ -38,7 +38,7 @@
     "evidence"
   ],
   "catalog": {
-    "sourceCommit": "a6584aeee5b2761e628cb8a90b22bdf2c6862359",
+    "sourceCommit": "251b4771b7e0f8f262041cc47f436d8b4f785537",
     "digest": "3195c901d6068ef7be8e9e23676b9b6ec58fb4e50c2d5604bbea390fefec9fdb"
   }
 }

package/policy.json

@@ -2,10 +2,11 @@
   "schemaVersion": 1,
   "registry": "https://registry.npmjs.org",
   "tools": {
-    "@volter/world-core": "3.0.98",
-    "@volter/world-runtime": "3.0.98",
-    "@volter/twin-standard": "1.0.90",
-    "playwright": "1.63.0"
+    "@volter/world-core": "3.0.100",
+    "@volter/world-runtime": "3.0.100",
+    "@volter/twin-standard": "1.0.92",
+    "playwright": "1.63.0",
+    "@volter/world": "3.0.100"
   },
   "bun": "1.4.2",
   "nodeImage": "node:24-bookworm-slim",

package/runner/Dockerfile

@@ -4,13 +4,18 @@ ARG BUN_VERSION=1.3.11
 ARG STANDARD_VERSION=1.0.37
 ARG CORE_VERSION=3.0.45
 ARG RUNTIME_VERSION=3.0.45
+ARG CLI_VERSION
 ARG PLAYWRIGHT_VERSION=1.63.0
 ENV PLAYWRIGHT_BROWSERS_PATH=/opt/playwright
-RUN apt-get update && apt-get install -y --no-install-recommends git openssl ca-certificates libfaketime && rm -rf /var/lib/apt/lists/*
+# Install native PostgreSQL tools without a distribution-owned cluster; each World owns its own data and lifetime.
+# https://manpages.debian.org/bookworm/postgresql-common/pg_createcluster.1.en.html#DEFAULT_VALUES
+RUN mkdir -p /etc/postgresql-common && printf 'create_main_cluster = false\n' > /etc/postgresql-common/createcluster.conf \
+    && apt-get update && apt-get install -y --no-install-recommends git openssl ca-certificates libfaketime postgresql-15 && rm -rf /var/lib/apt/lists/*
+ENV VOLTER_WORLD_POSTGRES_BIN=/usr/lib/postgresql/15/bin
 WORKDIR /opt/catalog
 RUN npm install --ignore-scripts --no-audit --no-fund --save-exact \
     @oven/bun-linux-x64@${BUN_VERSION} @volter/twin-standard@${STANDARD_VERSION} \
-    @volter/world-core@${CORE_VERSION} @volter/world-runtime@${RUNTIME_VERSION} tar@7.5.7 semver@7.8.5 sigstore@4.1.1 playwright@${PLAYWRIGHT_VERSION}
+    @volter/world-core@${CORE_VERSION} @volter/world-runtime@${RUNTIME_VERSION} @volter/world@${CLI_VERSION} tar@7.5.7 semver@7.8.5 sigstore@4.1.1 playwright@${PLAYWRIGHT_VERSION}
 ENV PATH="/opt/catalog/node_modules/@oven/bun-linux-x64/bin:/opt/catalog/node_modules/.bin:${PATH}"
 RUN ./node_modules/.bin/playwright install --with-deps chromium
 COPY lib /opt/catalog/lib

package/runner/evaluate.mjs

@@ -7,9 +7,10 @@ requireThat(Boolean(process.env.VOLTER_WORLD), 'evaluation must run inside a Wor
 const { submission: s } = read('/input/input.json');
 const requireFromPack = createRequire('/work/package.json');
 const { assessPack } = await import(requireFromPack.resolve('@volter/twin-standard'));
-const assessment = await assessPack(join('/work/packs', s.vendor), { browser: true });
+const prepared = read('/work/prepared.json');
+const assessment = await assessPack(join('/work/packs', s.vendor), { browser: true, consumer: prepared.consumer });
 requireThat(assessment.package === s.package && assessment.version === s.version && assessment.vendor === s.vendor, 'assessment returned a different artifact identity');
-const report = { ...assessment, integrity: s.integrity, prepared: read('/work/prepared.json') };
+const report = { ...assessment, integrity: s.integrity, prepared };
 report.comparison = compareReports(report, existsSync('/input/baseline.json') ? read('/input/baseline.json') : null);
 write('/work/report.json', report);
 process.exit(report.ready ? 0 : 1);

package/runner/prepare.mjs

@@ -81,6 +81,18 @@ const provenance = await verifiedProvenance(await response.json(), source, bytes
 // Keep a vendor-named package directory for the standard's public directory API; preserve the installed artifact.
 mkdirSync('/work/packs', { recursive: true });
 cpSync(join('/work/node_modules', s.package), join('/work/packs', s.vendor), { recursive: true });
+const { prepareConsumerApp } = await import(evaluatorRequire.resolve('@volter/twin-standard'));
+const appDir = '/work/customer-app';
+const consumerFixture = prepareConsumerApp(join('/work/packs', s.vendor), appDir);
+const appInstall = spawnSync('npm', ['install', '--ignore-scripts', '--no-audit', '--no-fund', '--registry', policy.registry], { cwd: appDir, encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 });
+requireThat(appInstall.status === 0, `customer SDK preparation failed: ${appInstall.stderr}`);
+const consumerLock = read(join(appDir, 'package-lock.json'));
+for (const [path, entry] of Object.entries(consumerLock.packages ?? {})) {
+  if (!path) continue;
+  requireThat(!entry.link && entry.resolved && entry.integrity, `${path}: customer dependency is not a locked registry artifact`);
+  registryURL(entry.resolved, policy.registry);
+}
+const consumer = { appDir, cli: '/work/node_modules/.bin/volter', artifactIntegrity: s.integrity };
 // Retain listing facts from these exact bytes, never the registry's moving latest metadata.
 const packageMetadata = {
   description: typeof pack.description === 'string' ? pack.description : null,
@@ -90,5 +102,5 @@ const packageMetadata = {
   repositoryDirectory: typeof pack.repository === 'object' ? pack.repository.directory ?? null : null,
   bugs: typeof pack.bugs === 'string' ? pack.bugs : pack.bugs?.url ?? null,
 };
-write('/work/prepared.json', { schemaVersion: 1, submission: s, integrity: s.integrity, provenance, packageMetadata, dependencyLockSha256: digest(readFileSync('/work/package-lock.json', 'utf8')), clientSdkLocks, clientDependencyChoices, tools: policy.tools });
+write('/work/prepared.json', { schemaVersion: 1, submission: s, integrity: s.integrity, provenance, packageMetadata, dependencyLockSha256: digest(readFileSync('/work/package-lock.json', 'utf8')), clientSdkLocks, clientDependencyChoices, tools: policy.tools, consumer, consumerFixture, consumerDependencyLockSha256: digest(readFileSync(join(appDir, 'package-lock.json'), 'utf8')) });
 write('/work/world.json', { id: 'catalog-assessment', network: { egress: [] }, services: [] });