@volter/twin-standard 1.0.113 → 1.0.115

package/README.md

@@ -8,6 +8,7 @@ place a pack is judged judges it by the same standard.
 ```bash
 twin-standard create <dir> --init <vendor> --package <@scope/name>  # fixed files, in your repository
 twin-standard create <unit> --index                         # fixed handler map and fetch after derivation
+twin-standard create <unit> --index --building              # construction only: keep unfinished operations as gaps
 twin-standard gate <pack repository> [<pack or lane dir>…]   # every unit passes the form section, or exit 1
 twin-standard gate-published <name>@<version>… [--registry <url>]  # a published version, as the catalog grades a submission
 twin-standard grade <pack or lane dir>… [--static] [--form]  # each criterion's result

package/dist/src/cli.js

@@ -31,7 +31,7 @@ import { standardPackageFile } from "./package-file.js";
 import { gatePublished } from "./published.js";
 const [command, ...args] = process.argv.slice(2);
 const usage = () => {
-    console.error('usage: twin-standard gate <repo> [units…] | gate-published <name>@<version>… [--registry <url>] | grade <unit>… [--static] [--form] | derive <unit> [--out <dir>] | read-page <url> [--raw] | check-sources <unit> [--recheck] | conform <pack dir> | <name>@<version> [--registry <url>] | create <dir> --init <vendor> --package <@scope/name> | create <unit> --index | facts <pack dir> [--out <file>] | prepare-consumer <pack dir> --app <new dir> --cli <volter executable> --integrity <sha512> --out <json> [--candidate <tgz>] | walk-consumer <pack dir> --prepared-consumer <json> [--out <file>] | assess <pack dir> --prepared-consumer <json> [--browser] [--out <file>] | --version');
+    console.error('usage: twin-standard gate <repo> [units…] | gate-published <name>@<version>… [--registry <url>] | grade <unit>… [--static] [--form] | derive <unit> [--out <dir>] | read-page <url> [--raw] | check-sources <unit> [--recheck] | conform <pack dir> | <name>@<version> [--registry <url>] | create <dir> --init <vendor> --package <@scope/name> | create <unit> --index [--building] | facts <pack dir> [--out <file>] | prepare-consumer <pack dir> --app <new dir> --cli <volter executable> --integrity <sha512> --out <json> [--candidate <tgz>] | walk-consumer <pack dir> --prepared-consumer <json> [--out <file>] | assess <pack dir> --prepared-consumer <json> [--browser] [--out <file>] | --version');
     process.exit(2);
 };
 if (command === '--version') {

package/dist/src/conformance.d.ts

@@ -26,8 +26,11 @@ type Decision = {
  *  the vendor's own API's operation of that id, or, when its own API has none, the one lane's that has it. So an id two
  *  units share is two decisions, and a lane's operation its root serves stays the lane's gap (Clerk's Backend and
  *  Frontend APIs both name `ListOrganizationMemberships`). A demanded operation (journeys/demand.json, the vendor's
- *  backend calls) is the unit's a row naming no lane would decide. */
-export declare function decisionTableProblems(unit: string, byUnit: Record<string, Owners>, decisions: Decision[], demanded?: string[], doors?: string[]): string[];
+ *  backend calls) is the unit's a row naming no lane would decide. Construction may leave unfinished operations as
+ *  gaps; the default and conformance callers require completion. Both modes hold implemented operations to the table. */
+export declare function decisionTableProblems(unit: string, byUnit: Record<string, Owners>, decisions: Decision[], demanded?: string[], doors?: string[], options?: {
+    building?: boolean;
+}): string[];
 /** Every check over the pack at `dir`, in order. */
 export declare function conformance(dir: string): Promise<ConformanceResult[]>;
 export {};

package/dist/src/conformance.js

@@ -73,8 +73,9 @@ const manifestOf = async (unit) => (await import(__rewriteRelativeImportExtensio
  *  the vendor's own API's operation of that id, or, when its own API has none, the one lane's that has it. So an id two
  *  units share is two decisions, and a lane's operation its root serves stays the lane's gap (Clerk's Backend and
  *  Frontend APIs both name `ListOrganizationMemberships`). A demanded operation (journeys/demand.json, the vendor's
- *  backend calls) is the unit's a row naming no lane would decide. */
-export function decisionTableProblems(unit, byUnit, decisions, demanded = [], doors = []) {
+ *  backend calls) is the unit's a row naming no lane would decide. Construction may leave unfinished operations as
+ *  gaps; the default and conformance callers require completion. Both modes hold implemented operations to the table. */
+export function decisionTableProblems(unit, byUnit, decisions, demanded = [], doors = [], options = {}) {
     const owners = { ...(byUnit[unit] ?? {}), ...Object.fromEntries(doors.map((id) => [`door:${id}`, 'door'])) };
     const holders = (id) => Object.keys(byUnit).filter((u) => id in byUnit[u]);
     const unnamedUnit = (id) => (id in (byUnit[''] ?? {}) ? '' : holders(id).length === 1 ? holders(id)[0] : undefined);
@@ -94,12 +95,13 @@ export function decisionTableProblems(unit, byUnit, decisions, demanded = [], do
     for (const d of mine) {
         if (!(d.operation in owners))
             out.push(`${d.operation} is decided for ${unit || 'the root'}, which has no such operation`);
-        else if (owners[d.operation] === 'gap' && d.mechanism !== 'unmodeled')
+        else if (!options.building && owners[d.operation] === 'gap' && d.mechanism !== 'unmodeled')
             out.push(`${d.operation} is decided ${d.mechanism} and served by nothing`);
     }
-    for (const op of demanded)
-        if (op && unnamedUnit(op) === unit && owners[op] === 'gap')
-            out.push(`${op} is demanded (journeys/demand.json) and served by nothing`);
+    if (!options.building)
+        for (const op of demanded)
+            if (op && unnamedUnit(op) === unit && owners[op] === 'gap')
+                out.push(`${op} is demanded (journeys/demand.json) and served by nothing`);
     return out;
 }
 /** Every operation a unit serves is decided, every operation demanded or refreshed is served (create-pack --index's

package/dist/src/create-pack.d.ts

@@ -8,7 +8,9 @@ export declare function handlerIndex(dir: string): string;
  *  serves, the demand it answers and the mechanism that serves it (`handler` or `core`); an operation it does not serve
  *  is `unmodeled` in the manifest. The unit's owners are the vendor's dispatch's for that unit. A problem stops the index:
  *  six packs once shipped answering 404 to everything, and scope once grew past demand, both unseen by the tools. */
-export declare function decisionProblems(dir: string): Promise<string[]>;
+export declare function decisionProblems(dir: string, options?: {
+    building?: boolean;
+}): Promise<string[]>;
 /** A unit's fetch.ts, a fixed file: `createPackFetch` over its parts as they stand (the manifest, the surface, the handler
  *  map, and its doors, clock and screens where it has them). `--init` writes it, and `--index` again when a door file,
  *  the clock or a screen is added. `name` is the fetch's export (`createClerkFetch`, a lane's `createFapiLaneFetch`). */

package/dist/src/create-pack.js

@@ -22,6 +22,8 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 //                                                          vendor facts, the descriptor's hosts and the families
 //   bun scripts/create-pack.ts <unit> --index            write src/semantics/index.ts, the handler map, and src/fetch.ts from the
 //                                                          families' files (every exported function, by its name)
+//   bun scripts/create-pack.ts <unit> --index --building the same during construction; unfinished operations stay gaps,
+//                                                          and implemented operations must match their decisions
 //   bun scripts/create-pack.ts <unit> --brief [--out f]  the author's brief: every operation the derived core does not
 //                                                          serve and no handler answers yet, by family, with what the
 //                                                          vendored spec says of it (summary, description, parameters,
@@ -101,7 +103,7 @@ export function handlerIndex(dir) {
  *  serves, the demand it answers and the mechanism that serves it (`handler` or `core`); an operation it does not serve
  *  is `unmodeled` in the manifest. The unit's owners are the vendor's dispatch's for that unit. A problem stops the index:
  *  six packs once shipped answering 404 to everything, and scope once grew past demand, both unseen by the tools. */
-export async function decisionProblems(dir) {
+export async function decisionProblems(dir, options = {}) {
     const out = [];
     const journeys = existsSync(join(dir, 'journeys')) ? join(dir, 'journeys') : join(dir, '..', 'journeys');
     const tablePath = join(journeys, 'decisions.json');
@@ -129,10 +131,10 @@ export async function decisionProblems(dir) {
     // a refresh reads the vendor's list or retrieve, and a World rooted at a second World's twin of the pack reads it from
     // that twin (pack-done's (g)): an operation a refresh scope names is one the pack serves
     const { manifest } = await import(__rewriteRelativeImportExtension(resolve(dir, 'src', 'manifest.ts')));
-    out.push(...decisionTableProblems(unit, byUnit, table.decisions ?? [], demanded, manifest?.doors?.map((d) => d.id) ?? []));
+    out.push(...decisionTableProblems(unit, byUnit, table.decisions ?? [], demanded, manifest?.doors?.map((d) => d.id) ?? [], options));
     for (const [name, decl] of Object.entries(manifest?.resources ?? {})) {
         for (const id of [decl.refresh?.list ?? decl.refresh?.get, decl.refresh?.detail])
-            if (id && id in owners && owners[id] === 'gap')
+            if (!options.building && id && id in owners && owners[id] === 'gap')
                 out.push(`${id}: ${name}'s refresh reads it, and nothing serves it (serve it, or declare refresh none with why)`);
     }
     return out;
@@ -454,7 +456,11 @@ export function laneInitFiles(vendor, lanes) {
 export async function createPack(args) {
     const [unit, ...rest] = args;
     if (!unit || (!rest.includes('--index') && !rest.includes('--brief') && !rest.includes('--init'))) {
-        console.error('usage: bun scripts/create-pack.ts <dir> --init <vendor> | <unit> --index | --brief [--out <file>]');
+        console.error('usage: bun scripts/create-pack.ts <dir> --init <vendor> | <unit> --index [--building] | --brief [--out <file>]');
+        process.exit(2);
+    }
+    if (rest.includes('--building') && (!rest.includes('--index') || rest.includes('--init') || rest.includes('--brief'))) {
+        console.error('create-pack: --building requires --index alone; it generates an unfinished pack, not completion evidence');
         process.exit(2);
     }
     const dir = resolve(unit);
@@ -576,12 +582,14 @@ export async function createPack(args) {
         if (odd)
             process.exit(1);
         if (!lanesOnly) {
-            const problems = await decisionProblems(dir);
+            const problems = await decisionProblems(dir, { building: rest.includes('--building') });
             if (problems.length) {
                 console.error(`create-pack: ${basename(dir)}: ${problems.length} problem(s) with what the unit serves:\n  ${problems.join('\n  ')}`);
                 process.exit(1);
             }
         }
+        if (rest.includes('--building'))
+            console.log('create-pack: construction index only; unfinished operations remain gaps; run ordinary --index before completion');
     }
     if (rest.includes('--brief')) {
         const text = await brief(unit);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/twin-standard",
-  "version": "1.0.113",
+  "version": "1.0.115",
   "description": "The Protocol 3 standard for Volter twin packs: the criteria a pack is graded by, the grader, the gate a pack repository and the twin catalog run on every change and submission, and the spec derivation the grade checks against. Pin a version: every place a pack is judged judges by that standard.",
   "keywords": [
     "twin",
@@ -75,7 +75,7 @@
     "yaml": "2.9.0"
   },
   "peerDependencies": {
-    "@volter/world-core": "3.0.121",
+    "@volter/world-core": "3.0.123",
     "@volter/world-runtime": "*",
     "playwright": "^1.63.0"
   },

package/src/cli.ts

@@ -24,7 +24,7 @@ import { gatePublished } from './published.ts';
 
 const [command, ...args] = process.argv.slice(2);
 const usage = (): never => {
-  console.error('usage: twin-standard gate <repo> [units…] | gate-published <name>@<version>… [--registry <url>] | grade <unit>… [--static] [--form] | derive <unit> [--out <dir>] | read-page <url> [--raw] | check-sources <unit> [--recheck] | conform <pack dir> | <name>@<version> [--registry <url>] | create <dir> --init <vendor> --package <@scope/name> | create <unit> --index | facts <pack dir> [--out <file>] | prepare-consumer <pack dir> --app <new dir> --cli <volter executable> --integrity <sha512> --out <json> [--candidate <tgz>] | walk-consumer <pack dir> --prepared-consumer <json> [--out <file>] | assess <pack dir> --prepared-consumer <json> [--browser] [--out <file>] | --version');
+  console.error('usage: twin-standard gate <repo> [units…] | gate-published <name>@<version>… [--registry <url>] | grade <unit>… [--static] [--form] | derive <unit> [--out <dir>] | read-page <url> [--raw] | check-sources <unit> [--recheck] | conform <pack dir> | <name>@<version> [--registry <url>] | create <dir> --init <vendor> --package <@scope/name> | create <unit> --index [--building] | facts <pack dir> [--out <file>] | prepare-consumer <pack dir> --app <new dir> --cli <volter executable> --integrity <sha512> --out <json> [--candidate <tgz>] | walk-consumer <pack dir> --prepared-consumer <json> [--out <file>] | assess <pack dir> --prepared-consumer <json> [--browser] [--out <file>] | --version');
   process.exit(2);
 };
 

package/src/conformance.ts

@@ -86,8 +86,9 @@ type Decision = { operation: string; mechanism: string; demand?: string; lane?:
  *  the vendor's own API's operation of that id, or, when its own API has none, the one lane's that has it. So an id two
  *  units share is two decisions, and a lane's operation its root serves stays the lane's gap (Clerk's Backend and
  *  Frontend APIs both name `ListOrganizationMemberships`). A demanded operation (journeys/demand.json, the vendor's
- *  backend calls) is the unit's a row naming no lane would decide. */
-export function decisionTableProblems(unit: string, byUnit: Record<string, Owners>, decisions: Decision[], demanded: string[] = [], doors: string[] = []): string[] {
+ *  backend calls) is the unit's a row naming no lane would decide. Construction may leave unfinished operations as
+ *  gaps; the default and conformance callers require completion. Both modes hold implemented operations to the table. */
+export function decisionTableProblems(unit: string, byUnit: Record<string, Owners>, decisions: Decision[], demanded: string[] = [], doors: string[] = [], options: { building?: boolean } = {}): string[] {
   const owners = { ...(byUnit[unit] ?? {}), ...Object.fromEntries(doors.map((id) => [`door:${id}`, 'door'])) };
   const holders = (id: string): string[] => Object.keys(byUnit).filter((u) => id in byUnit[u]!);
   const unnamedUnit = (id: string): string | undefined => (id in (byUnit[''] ?? {}) ? '' : holders(id).length === 1 ? holders(id)[0] : undefined);
@@ -103,9 +104,9 @@ export function decisionTableProblems(unit: string, byUnit: Record<string, Owner
   }
   for (const d of mine) {
     if (!(d.operation in owners)) out.push(`${d.operation} is decided for ${unit || 'the root'}, which has no such operation`);
-    else if (owners[d.operation] === 'gap' && d.mechanism !== 'unmodeled') out.push(`${d.operation} is decided ${d.mechanism} and served by nothing`);
+    else if (!options.building && owners[d.operation] === 'gap' && d.mechanism !== 'unmodeled') out.push(`${d.operation} is decided ${d.mechanism} and served by nothing`);
   }
-  for (const op of demanded) if (op && unnamedUnit(op) === unit && owners[op] === 'gap') out.push(`${op} is demanded (journeys/demand.json) and served by nothing`);
+  if (!options.building) for (const op of demanded) if (op && unnamedUnit(op) === unit && owners[op] === 'gap') out.push(`${op} is demanded (journeys/demand.json) and served by nothing`);
   return out;
 }
 

package/src/create-pack.ts

@@ -14,6 +14,8 @@
 //                                                          vendor facts, the descriptor's hosts and the families
 //   bun scripts/create-pack.ts <unit> --index            write src/semantics/index.ts, the handler map, and src/fetch.ts from the
 //                                                          families' files (every exported function, by its name)
+//   bun scripts/create-pack.ts <unit> --index --building the same during construction; unfinished operations stay gaps,
+//                                                          and implemented operations must match their decisions
 //   bun scripts/create-pack.ts <unit> --brief [--out f]  the author's brief: every operation the derived core does not
 //                                                          serve and no handler answers yet, by family, with what the
 //                                                          vendored spec says of it (summary, description, parameters,
@@ -93,7 +95,7 @@ export function handlerIndex(dir: string): string {
  *  serves, the demand it answers and the mechanism that serves it (`handler` or `core`); an operation it does not serve
  *  is `unmodeled` in the manifest. The unit's owners are the vendor's dispatch's for that unit. A problem stops the index:
  *  six packs once shipped answering 404 to everything, and scope once grew past demand, both unseen by the tools. */
-export async function decisionProblems(dir: string): Promise<string[]> {
+export async function decisionProblems(dir: string, options: { building?: boolean } = {}): Promise<string[]> {
   const out: string[] = [];
   const journeys = existsSync(join(dir, 'journeys')) ? join(dir, 'journeys') : join(dir, '..', 'journeys');
   const tablePath = join(journeys, 'decisions.json');
@@ -119,9 +121,9 @@ export async function decisionProblems(dir: string): Promise<string[]> {
   // a refresh reads the vendor's list or retrieve, and a World rooted at a second World's twin of the pack reads it from
   // that twin (pack-done's (g)): an operation a refresh scope names is one the pack serves
   const { manifest } = await import(resolve(dir, 'src', 'manifest.ts')) as { manifest?: { doors?: Array<{ id: string }>; resources?: Record<string, { refresh?: { list?: string; detail?: string; get?: string } }> } };
-  out.push(...decisionTableProblems(unit, byUnit, table.decisions ?? [], demanded, manifest?.doors?.map((d) => d.id) ?? []));
+  out.push(...decisionTableProblems(unit, byUnit, table.decisions ?? [], demanded, manifest?.doors?.map((d) => d.id) ?? [], options));
   for (const [name, decl] of Object.entries(manifest?.resources ?? {})) {
-    for (const id of [decl.refresh?.list ?? decl.refresh?.get, decl.refresh?.detail]) if (id && id in owners && owners[id] === 'gap') out.push(`${id}: ${name}'s refresh reads it, and nothing serves it (serve it, or declare refresh none with why)`);
+    for (const id of [decl.refresh?.list ?? decl.refresh?.get, decl.refresh?.detail]) if (!options.building && id && id in owners && owners[id] === 'gap') out.push(`${id}: ${name}'s refresh reads it, and nothing serves it (serve it, or declare refresh none with why)`);
   }
   return out;
 }
@@ -447,7 +449,11 @@ export function laneInitFiles(vendor: string, lanes: string[]): Record<string, s
 export async function createPack(args: string[]): Promise<void> {
   const [unit, ...rest] = args;
   if (!unit || (!rest.includes('--index') && !rest.includes('--brief') && !rest.includes('--init'))) {
-    console.error('usage: bun scripts/create-pack.ts <dir> --init <vendor> | <unit> --index | --brief [--out <file>]');
+    console.error('usage: bun scripts/create-pack.ts <dir> --init <vendor> | <unit> --index [--building] | --brief [--out <file>]');
+    process.exit(2);
+  }
+  if (rest.includes('--building') && (!rest.includes('--index') || rest.includes('--init') || rest.includes('--brief'))) {
+    console.error('create-pack: --building requires --index alone; it generates an unfinished pack, not completion evidence');
     process.exit(2);
   }
   const dir = resolve(unit);
@@ -530,9 +536,10 @@ export async function createPack(args: string[]): Promise<void> {
     }
     if (odd) process.exit(1);
     if (!lanesOnly) {
-      const problems = await decisionProblems(dir);
+      const problems = await decisionProblems(dir, { building: rest.includes('--building') });
       if (problems.length) { console.error(`create-pack: ${basename(dir)}: ${problems.length} problem(s) with what the unit serves:\n  ${problems.join('\n  ')}`); process.exit(1); }
     }
+    if (rest.includes('--building')) console.log('create-pack: construction index only; unfinished operations remain gaps; run ordinary --index before completion');
   }
   if (rest.includes('--brief')) {
     const text = await brief(unit);