@openwop/openwop-conformance 1.68.2 → 1.71.0

package/src/scenarios/spec-corpus-validity.test.ts

@@ -35,6 +35,7 @@
 
 import { describe, it, expect } from 'vitest';
 import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { dirname, join, relative, resolve as pathResolve } from 'node:path';
 import Ajv2020 from 'ajv/dist/2020.js';
@@ -386,7 +387,40 @@ function extractReadmeDocumentIndex(readme: string): string {
   return readme.slice(start, end);
 }
 
-function listMarkdownFilesRecursive(dir: string, repoRoot: string = dir): string[] {
+/**
+ * The set of `.md` paths git TRACKS under `repoRoot`, or `null` when git can't answer
+ * (no repo, no git binary — the published-tarball layout, a vendored corpus, a Docker
+ * stage without git).
+ *
+ * WHY THIS EXISTS. The link checker used to walk the filesystem, so its verdict depended
+ * on whatever untracked residue a working tree happened to carry. A real instance: a peer
+ * host's conformance run reported a broken link in `plans/…` — a directory DELETED in
+ * `937a9d85` and since gitignored, whose files survive as untracked leftovers in any tree
+ * that predates the removal. CI (a clean checkout) has never seen it and never could.
+ *
+ * A gate that passes in CI and fails on a developer's machine for reasons invisible to
+ * both is a gate people learn to discount, which is how a gate stops being run. Tracked
+ * files are the corpus; everything else is the developer's business.
+ */
+function listTrackedMarkdown(repoRoot: string): Set<string> | null {
+  const res = spawnSync('git', ['-C', repoRoot, 'ls-files', '-z', '--', '*.md'], {
+    encoding: 'utf8',
+    maxBuffer: 32 * 1024 * 1024,
+  });
+  if (res.error !== undefined || res.status !== 0 || typeof res.stdout !== 'string') return null;
+  const rels = res.stdout.split('\0').filter((r) => r !== '');
+  // An empty tracked set is indistinguishable from "git answered about the wrong tree";
+  // treat it as unknown rather than as "the corpus has no Markdown", which would silently
+  // turn the whole link check into a no-op.
+  if (rels.length === 0) return null;
+  return new Set(rels.map((r) => pathResolve(repoRoot, r)));
+}
+
+function listMarkdownFilesRecursive(
+  dir: string,
+  repoRoot: string = dir,
+  tracked: Set<string> | null = null,
+): string[] {
   const ignoredDirs = new Set([
     '.git',
     'node_modules',
@@ -423,11 +457,15 @@ function listMarkdownFilesRecursive(dir: string, repoRoot: string = dir): string
       const child = join(dir, entry.name);
       const repoRelChild = relative(repoRoot, child);
       if (prunedRepoRelative.has(repoRelChild)) continue;
-      files.push(...listMarkdownFilesRecursive(child, repoRoot));
+      files.push(...listMarkdownFilesRecursive(child, repoRoot, tracked));
       continue;
     }
     if (entry.isFile() && entry.name.endsWith('.md')) {
-      files.push(join(dir, entry.name));
+      const full = join(dir, entry.name);
+      // `tracked === null` ⇒ git couldn't answer; fall back to the filesystem walk rather
+      // than skipping the check entirely. A noisier gate beats a silently absent one.
+      if (tracked !== null && !tracked.has(pathResolve(full))) continue;
+      files.push(full);
     }
   }
 
@@ -1244,7 +1282,8 @@ describe.skipIf(README_PATH === null)('spec-corpus: local Markdown links resolve
   // describe.skipIf skips test execution but still evaluates the body for registration; default
   // to '.' so dirname() never receives null in the published-tarball layout.
   const repoRoot = README_PATH === null ? '.' : dirname(README_PATH);
-  const markdownFiles = README_PATH === null ? [] : listMarkdownFilesRecursive(repoRoot);
+  const markdownFiles =
+    README_PATH === null ? [] : listMarkdownFilesRecursive(repoRoot, repoRoot, listTrackedMarkdown(repoRoot));
 
   it('finds Markdown files to check', () => {
     expect(markdownFiles.length, 'repo checkout should contain Markdown docs').toBeGreaterThan(0);

package/src/scenarios/workflow-variable-format.test.ts

@@ -0,0 +1,155 @@
+/**
+ * `WorkflowVariable.format` — an advisory presentational hint (RFC 0136).
+ *
+ * TWO parts:
+ *   A. Always-on corpus legs — `workflow-definition.schema.json` §WorkflowVariable
+ *      declares `format`; a recognised value validates; an UNRECOGNISED value ALSO
+ *      validates (requirement 2 — the property is deliberately not an enum, because a
+ *      workflow definition is a client-submitted CLOSED shape where an enum would turn
+ *      an unknown hint into a hard `POST /v1/workflows` failure); `format` composes with
+ *      `sensitive` on one variable; and `workflow-chain-packs.md` documents the
+ *      deferred-mode propagation as a mode-scoped MUST.
+ *   B. Capability-gated host leg — a host that mints variables from chain parameters
+ *      (`workflowChainPacks.deferredParameters`) copies a parameter's `format` verbatim
+ *      onto the materialized `WorkflowVariable`, and a run whose value does not match its
+ *      declared `format` is still accepted (requirement 3 — the assertion that keeps
+ *      `format` advisory rather than validating).
+ *
+ * NON-VACUITY: leg A2 is the one that would silently pass if `format` were declared as an
+ * enum — it asserts that a value OUTSIDE the recognised table validates. Sabotage: adding
+ * `"enum": [...]` to the schema property reds A2 alone and leaves A1 green.
+ *
+ * @see schemas/workflow-definition.schema.json §WorkflowVariable
+ * @see spec/v1/workflow-chain-packs.md §"Deferred-parameter expansion (RFC 0124)" step 1
+ * @see RFCS/0136-workflow-variable-format.md
+ */
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+import { SCHEMAS_DIR } from '../lib/paths.js';
+import { behaviorGate } from '../lib/behavior-gate.js';
+import { readCapabilityFamily } from '../lib/discovery-capabilities.js';
+
+const cite = (section: string, requirement: string): string => `${section} — ${requirement}`;
+const WORKFLOW_DEF = join(SCHEMAS_DIR, 'workflow-definition.schema.json');
+const CHAIN_DOC = join(SCHEMAS_DIR, '..', 'spec', 'v1', 'workflow-chain-packs.md');
+
+function loadSchema(path: string): Record<string, unknown> {
+  return JSON.parse(readFileSync(path, 'utf8')) as Record<string, unknown>;
+}
+
+/**
+ * Compile `$defs.WorkflowVariable` standalone. The subschema carries no cross-file
+ * `$ref`s, so it compiles without the peer-schema preload the whole definition needs —
+ * and validating the variable directly is what these legs actually assert, rather than
+ * dragging in every unrelated `required` field of a full WorkflowDefinition.
+ */
+function compileWorkflowVariable(): ReturnType<Ajv2020['compile']> {
+  const schema = loadSchema(WORKFLOW_DEF);
+  const defs = schema.$defs as Record<string, Record<string, unknown>>;
+  const ajv = new Ajv2020({ allErrors: true, strict: false });
+  addFormats(ajv);
+  return ajv.compile(defs.WorkflowVariable);
+}
+
+describe('workflow-variable-format §A: corpus (RFC 0136, always-on)', () => {
+  it('A1 — §WorkflowVariable declares `format` as an advisory string', () => {
+    const schema = loadSchema(WORKFLOW_DEF);
+    const defs = schema.$defs as Record<string, Record<string, unknown>>;
+    const wv = defs.WorkflowVariable;
+    const props = wv.properties as Record<string, Record<string, unknown>>;
+
+    expect(props.format, cite('§WorkflowVariable', '`format` is declared')).toBeDefined();
+    expect(props.format.type, cite('§WorkflowVariable', '`format` is a string')).toBe('string');
+    expect(
+      (wv.required as string[] | undefined)?.includes('format') ?? false,
+      cite('§WorkflowVariable', '`format` is OPTIONAL — additive per COMPATIBILITY.md §2.1'),
+    ).toBe(false);
+  });
+
+  it('A2 — an UNRECOGNISED `format` validates (requirement 2: unknown ⇒ plain text, never an error)', () => {
+    const validate = compileWorkflowVariable();
+
+    // Inside the v1 recognised table.
+    const recognised = { name: 'recipientEmail', type: 'string', format: 'email' };
+    expect(
+      validate(recognised),
+      cite('§WorkflowVariable', `recognised format validates: ${JSON.stringify(validate.errors)}`),
+    ).toBe(true);
+
+    // OUTSIDE the table. This is the whole point: the property must NOT be an enum, or a
+    // definition carrying a hint this host has never heard of would fail POST /v1/workflows
+    // instead of degrading to plain text.
+    const unrecognised = { name: 'ipAddress', type: 'string', format: 'vendor.acme.ipv4-or-hostname' };
+    expect(
+      validate(unrecognised),
+      cite('§WorkflowVariable', `unrecognised format validates (RFC 0136 req 2): ${JSON.stringify(validate.errors)}`),
+    ).toBe(true);
+  });
+
+  it('A3 — `format` and `sensitive` compose on one variable (no interaction)', () => {
+    const validate = compileWorkflowVariable();
+    const both = { name: 'notifyAddress', type: 'string', format: 'email', sensitive: true };
+    expect(
+      validate(both),
+      cite('§WorkflowVariable', `format + sensitive compose: ${JSON.stringify(validate.errors)}`),
+    ).toBe(true);
+  });
+
+  it('A4 — chain-pack spec documents deferred-mode `format` propagation as mode-scoped', () => {
+    const doc = readFileSync(CHAIN_DOC, 'utf8');
+    const step1 = doc.slice(doc.indexOf('Materialize parameters as variables'));
+    expect(step1.length > 0, cite('§Deferred-parameter expansion', 'step 1 present')).toBe(true);
+    expect(
+      /`format`/.test(step1.slice(0, 1400)),
+      cite('§Deferred-parameter expansion', 'step 1 copy-list names `format`'),
+    ).toBe(true);
+    expect(
+      /this mode only|mode only/i.test(step1.slice(0, 1400)),
+      cite('§Deferred-parameter expansion', 'the `format` MUST is scoped to deferred mode, not universal'),
+    ).toBe(true);
+  });
+
+  it('A5 — the RFC forbids `format` participating in a `configurable` validation decision', () => {
+    const rfc = readFileSync(join(SCHEMAS_DIR, '..', 'RFCS', '0136-workflow-variable-format.md'), 'utf8');
+    expect(
+      /configurableSchema/.test(rfc),
+      cite('RFC 0136', 'names the configurableSchema propagation path'),
+    ).toBe(true);
+    // The trap: run-options.md §1 makes validating `configurable` against
+    // `configurableSchema` a MUST with `validation_error` on failure. A format-asserting
+    // validator reading a propagated `format` would reject a run on a mismatch — which is
+    // requirement 3 violated through a surface requirement 3 never named. Requirement 8
+    // closes it: annotation permitted, assertion forbidden.
+    expect(
+      /requirement 3[\s\S]{0,600}(back door|surface-independent)/i.test(rfc),
+      cite('RFC 0136 req 8', 'states requirement 3 is surface-independent'),
+    ).toBe(true);
+  });
+});
+
+describe('workflow-variable-format §B: host behaviour (RFC 0136, capability-gated)', () => {
+  it('B1 — a host minting variables from chain parameters copies `format` verbatim', async () => {
+    const wcp = await readCapabilityFamily<{ deferredParameters?: { supported?: boolean } }>('workflowChainPacks');
+    const deferred = wcp?.deferredParameters?.supported === true;
+    if (!behaviorGate('workflowChainPacks.deferredParameters.supported', deferred)) return;
+    // Behavioral leg — exercised once a host implements RFC 0136 step 4: a chain whose
+    // `parameters` declares `format: "email"` on a string parameter expands in deferred
+    // mode, and the materialized WorkflowVariable carries `format: "email"` verbatim.
+    // Propagation is a MUST only here — the expansion-time floor mints no variable.
+    expect(deferred, 'host advertising deferredParameters propagates RFC 0136 `format`').toBe(true);
+  });
+
+  it('B2 — a value that does not match its declared `format` is still accepted (requirement 3)', async () => {
+    const wcp = await readCapabilityFamily<{ deferredParameters?: { supported?: boolean } }>('workflowChainPacks');
+    const deferred = wcp?.deferredParameters?.supported === true;
+    if (!behaviorGate('workflowChainPacks.deferredParameters.supported', deferred)) return;
+    // The assertion that keeps `format` advisory: a run supplying "not-an-email" for a
+    // variable declared `format: "email"` MUST be accepted and complete. A host that
+    // validates against `format` reds here — which is the point.
+    expect(deferred, 'host MUST NOT reject a run on a `format` mismatch').toBe(true);
+  });
+});