@b00dea/cockpit 0.1.0 → 0.1.1

package/dist/work-orders/composition.js

@@ -2,6 +2,7 @@ import { createHash, randomUUID } from 'node:crypto';
 import {} from '../schema.js';
 import { sha256Hex } from '../sha256.js';
 import { closeSync, constants, existsSync, fstatSync, lstatSync, openSync, readSync, realpathSync, readdirSync, } from 'node:fs';
+import { mkdir, open as openFile, rm } from 'node:fs/promises';
 import { basename, delimiter, dirname, isAbsolute, join, parse as parsePath, relative, resolve, sep } from 'node:path';
 import { isProxy } from 'node:util/types';
 import { readBoundedFile } from '../bounded-read.js';
@@ -18,21 +19,29 @@ import { isGuardSurfaceTarget } from '../surfaces/harness-registry.js';
 import { cockpitCommand } from '../fix-catalogue.js';
 import { stripDevelopmentMarkers } from '../surfaces/development-markers.js';
 import { decodeLifecycleRecord } from '../environment/application/lifecycle.js';
-import { resolveExecutablePath } from '../environment/executable.js';
+import { selectLocalDockerDaemon } from '../environment/docker-daemon.js';
+import { resolveDockerExecutable, resolveExecutablePath } from '../environment/executable.js';
+import { discoverMachineStacks } from '../environment/reclaim.js';
 import { consumeWorkApplicationAuthorities, prepareWorkApplicationAuthorities, projectWorkApplicationAuthorities, } from '../environment/generated-application/authorities.js';
 import { prepareGeneratedEnvironmentCurrentness } from '../environment/generated-application/check.js';
 import { createLifecycleCommandAdapters } from '../environment/lifecycle-composition.js';
 import { createReadCommandAdapters } from '../environment/read-composition.js';
 import { deriveEntrypoints, observeRetainedPortFamily } from '../environment/ports.js';
 import { readState } from '../environment/state.js';
+import { parseDiff } from '../testing/test-protection.js';
+import { testFilePatterns, weakeningFindings } from '../testing/weakening.js';
 import { runGate } from '../testing/gates.js';
-import { parseCriteriaFile, parseWorkOrder, WORK_ORDER_ID } from './contract.js';
+import { readSiblingCheckouts, missingServedCheckout, servedPath, servedSiblings } from '../environment/sibling-checkouts.js';
+import { splitRepositoryPath } from '../repository-path.js';
+import { parseCriteriaFile, parseWorkOrder, scopeMatcher, WORK_ORDER_ID } from './contract.js';
 import { createWorkStore, outputTail, WORK_RECORD_DIRECTORY } from './store.js';
 const issuedCompositions = new WeakSet();
 const MAX_DOCUMENT_BYTES = 8 * 1_048_576;
 const MAX_REPOSITORY_PATHS = 4_096;
 const MAX_REPOSITORY_FILE_BYTES = 8 * 1_048_576;
 const MAX_REPOSITORY_AGGREGATE_BYTES = 64 * 1_048_576;
+const MAX_DECISION_RECORDS = 4_096;
+const MAX_DECISION_RECORD_BYTES = 262_144;
 // What the grader is shown of one changed file, and of the whole change.
 const MAX_DIFF_BYTES = 65_536;
 const MAX_CHANGE_BYTES = 1_048_576;
@@ -200,6 +209,34 @@ function readBounded(root, relativePath, maximum = MAX_DOCUMENT_BYTES) {
         throw new RefusalError('contained file is missing');
     return readAnchoredLeaf(anchored, maximum, 'contained file');
 }
+// Node has no openat, so a write cannot name its file relative to a directory descriptor. Every ancestor is
+// anchored by descriptor instead, the leaf is opened without following a link, and nothing is written until
+// the opened file is shown to be the single-link regular file at the confined name, under ancestors that are
+// still the anchored directories: one swapped for a link while the file was opened fails that check.
+async function openContainedForWrite(root, relativePath, flags) {
+    // No ancestor's contents are bound: the write itself changes the directory that holds the file.
+    const anchored = anchoredReadPath(root, relativePath, false, join(root, relativePath));
+    if (!anchored)
+        throw new RefusalError('contained path is missing');
+    try {
+        const handle = await openFile(anchored.target, flags | constants.O_WRONLY | constants.O_NOFOLLOW, 0o644);
+        try {
+            const opened = await handle.stat({ bigint: true });
+            const named = lstatSync(anchored.target, { bigint: true, throwIfNoEntry: false });
+            if (!opened.isFile() || opened.nlink !== 1n || opened.dev !== named?.dev || opened.ino !== named.ino || !readAnchorsCurrent(anchored.anchors)) {
+                throw new RefusalError('contained file or an ancestor changed while it was opened for writing; nothing was written');
+            }
+            return handle;
+        }
+        catch (error) {
+            await handle.close();
+            throw error;
+        }
+    }
+    finally {
+        closeReadAnchors(anchored.anchors);
+    }
+}
 function readExactFile(path, maximum) {
     const anchored = anchoredAbsoluteReadPath(path);
     try {
@@ -395,11 +432,10 @@ function excludedRepositoryPath(path, excluded) {
         ? path === candidate.slice(0, -1) || path.startsWith(candidate)
         : path === candidate);
 }
-function repositoryEnvironmentInstancePaths(repositoryRoot, siblingsRoot, siblings) {
+function repositoryEnvironmentInstancePaths(repositoryRoot, siblings) {
     const paths = new Set();
     for (const sibling of siblings) {
-        const siblingRoot = resolve(siblingsRoot, sibling.dir);
-        const prefix = relative(repositoryRoot, siblingRoot);
+        const prefix = relative(repositoryRoot, sibling.root);
         if (isAbsolute(prefix) || prefix === '..' || prefix.startsWith(`..${sep}`))
             continue;
         for (const file of sibling.environmentFiles)
@@ -549,12 +585,13 @@ async function observeRepositorySubject(repository, excluded, directories, sensi
 export function isWorkApplicationComposition(value) {
     return value !== null && typeof value === 'object' && issuedCompositions.has(value);
 }
-function createWorkApplicationComposition(config, authorities) {
+function createWorkApplicationComposition(config, authorities, served) {
     if (!config || isProxy(config) || !boundedName(config.cockpitName) || !isAbsolute(config.cockpitRoot)
         || realpathSync(config.cockpitRoot) !== config.cockpitRoot || dirname(config.source.path) !== config.cockpitRoot
         || typeof config.siblingsRoot !== 'string' || !config.siblingsRoot || config.siblingsRoot.includes('\0')
         || !Array.isArray(config.siblings) || config.siblings.some(row => !boundedName(row?.slug) || typeof row?.dir !== 'string'
         || isAbsolute(row.dir) || row.dir !== '.' && row.dir.split(/[\\/]/).some((part) => !part || part === '.' || part === '..'))
+        || config.siblings.some(row => !isAbsolute(served.get(row.slug)?.served ?? ''))
         || !authorities || isProxy(authorities))
         throw new RefusalError('work application composition requires admitted source-bound configuration');
     const root = config.cockpitRoot;
@@ -564,19 +601,21 @@ function createWorkApplicationComposition(config, authorities) {
     const directories = authorities.executableDirectories ?? DEFAULT_EXECUTABLE_DIRECTORIES;
     const browserAuthenticationTargets = new Set((config.browser?.authentication.states ?? []).map(row => resolve(root, row.path)));
     // The cockpit's own repository is `.`; a sibling is named by its slug, and its paths read `<slug>:path`.
-    // A sibling checked out at the cockpit root is that same repository, under the cockpit's key.
-    const repositories = [{ key: '.', identity: config.cockpitName, root }, ...config.siblings.flatMap(row => resolve(siblingsRoot, row.dir) === root ? []
-            : [{ key: row.slug, identity: `siblings/${row.slug}`, root: resolve(siblingsRoot, row.dir) }])]
-        .map(repository => ({ ...repository, sensitivePaths: repositoryEnvironmentInstancePaths(repository.root, siblingsRoot, config.siblings) }));
-    const keyOf = (key) => config.siblings.some(row => row.slug === key && resolve(siblingsRoot, row.dir) === root) ? '.' : key;
+    // A sibling is read where it is served, which `cockpit use` may have moved to a worktree, so a grade
+    // judges the code the stack runs. One served at the cockpit root is that same repository, under the cockpit's key.
+    const servedRoot = (slug) => servedPath(served, slug);
+    const siblingRoots = config.siblings.map(row => ({ root: servedRoot(row.slug), environmentFiles: row.environmentFiles }));
+    const repositories = [{ key: '.', identity: config.cockpitName, root }, ...config.siblings.flatMap(row => servedRoot(row.slug) === root ? []
+            : [{ key: row.slug, identity: `siblings/${row.slug}`, root: servedRoot(row.slug) }])]
+        .map(repository => ({ ...repository, sensitivePaths: repositoryEnvironmentInstancePaths(repository.root, siblingRoots) }));
+    const keyOf = (key) => config.siblings.some(row => row.slug === key && servedRoot(row.slug) === root) ? '.' : key;
     const qualified = (key, path) => key === '.' ? path : `${key}:${path}`;
     const located = (reference) => {
-        const colon = reference.indexOf(':');
-        const key = colon < 0 ? '.' : keyOf(reference.slice(0, colon));
+        const { slug, path } = splitRepositoryPath(reference);
+        const key = slug === undefined ? '.' : keyOf(slug);
         const repository = repositories.find(row => row.key === key);
         if (!repository)
             throw new RefusalError(`${reference} names no declared sibling ${key}`);
-        const path = colon < 0 ? reference : reference.slice(colon + 1);
         admitRepositoryPath(repository.root, repository.identity, path, repository.sensitivePaths, browserAuthenticationTargets);
         return { repository, path };
     };
@@ -591,6 +630,100 @@ function createWorkApplicationComposition(config, authorities) {
             throw error;
         }
     };
+    const readDocsFile = async (reference) => {
+        const { repository, path } = located(reference);
+        try {
+            return readBounded(repository.root, path, MAX_DECISION_RECORD_BYTES).toString('utf8');
+        }
+        catch (error) {
+            if (hasErrorCode(error, 'ENOENT', 'ENOTDIR'))
+                return undefined;
+            throw error;
+        }
+    };
+    const decisionRecords = async () => {
+        const declared = config.docs?.decisions;
+        if (!declared)
+            return new Map();
+        const { repository, path } = located(declared);
+        let names;
+        try {
+            names = readdirSync(contained(repository.root, path, true));
+        }
+        catch (error) {
+            if (hasErrorCode(error, 'ENOENT'))
+                return new Map();
+            throw error;
+        }
+        const records = names.filter(name => name.endsWith('.md') && lstatSync(join(repository.root, path, name)).isFile()).sort();
+        if (records.length > MAX_DECISION_RECORDS)
+            throw new RefusalError(`[docs] decisions ${declared} holds more than ${MAX_DECISION_RECORDS} records, more than cockpit reads`);
+        return new Map(records.map(name => [`${declared}/${name}`, readBounded(repository.root, `${path}/${name}`, MAX_DECISION_RECORD_BYTES).toString('utf8')]));
+    };
+    // The only files cockpit writes outside .cockpit/: a decision record it scaffolds or marks superseded, and the index line.
+    // Each is written through a descriptor opened by openContainedForWrite; a replacement is written in place, as a
+    // rename would name its target by path again.
+    const writeContained = async (repository, path, flags, text, replace = false) => {
+        const handle = await openContainedForWrite(repository.root, path, flags);
+        try {
+            if (replace)
+                await handle.truncate(0);
+            await handle.writeFile(text);
+        }
+        finally {
+            await handle.close();
+        }
+    };
+    // A write that fails part way puts back what it changed, so a rerun does not number a second record or mark the old one twice.
+    const writeDecisionRecords = async (writes, indexLine) => {
+        const undo = [];
+        try {
+            for (const { reference, text, create } of writes) {
+                const { repository, path } = located(reference);
+                await mkdir(dirname(contained(repository.root, path, true)), { recursive: true });
+                const target = contained(repository.root, path, true);
+                if (create) {
+                    try {
+                        await writeContained(repository, path, constants.O_CREAT | constants.O_EXCL, text);
+                    }
+                    catch (error) {
+                        if (hasErrorCode(error, 'EEXIST'))
+                            throw new RefusalError(`${reference} already exists; rerun work decide, which takes the next free name`);
+                        throw error;
+                    }
+                    undo.push(() => rm(target, { force: true }));
+                    continue;
+                }
+                const previous = readBounded(repository.root, path, MAX_DECISION_RECORD_BYTES).toString('utf8');
+                // Queued before the write: an in-place write that fails after truncating has already changed the record.
+                undo.push(() => writeContained(repository, path, 0, previous, true));
+                await writeContained(repository, path, 0, text, true);
+            }
+            if (indexLine === undefined)
+                return;
+            if (!config.docs?.decisionsIndex)
+                throw new RefusalError('an index line was given but [docs] decisions_index is not declared');
+            const index = located(config.docs.decisionsIndex);
+            const current = readBounded(index.repository.root, index.path, MAX_DECISION_RECORD_BYTES).toString('utf8');
+            await writeContained(index.repository, index.path, constants.O_APPEND, `${current === '' || current.endsWith('\n') ? '' : '\n'}${indexLine}\n`);
+        }
+        catch (error) {
+            // Every step is tried, so one that fails does not leave the files after it changed.
+            const failed = [];
+            for (const step of undo.reverse()) {
+                try {
+                    await step();
+                }
+                catch (undoError) {
+                    failed.push(errorCause(undoError));
+                }
+            }
+            if (failed.length)
+                throw new RefusalError(`${errorCause(error)}; putting back the decision records also failed (${failed.join('; ')}); `
+                    + 'compare the [docs] decisions directory with git diff and restore what changed with git restore');
+            throw error;
+        }
+    };
     const git = async (repository, args) => {
         const observed = await executeBounded(repository.root, ['git', ...args], directories);
         if (observed.kind !== 'executed' || observed.exitCode !== 0 || observed.truncated)
@@ -621,12 +754,12 @@ function createWorkApplicationComposition(config, authorities) {
             throw error;
         }
     };
-    const browser = async (kind, role) => {
+    const browser = async (kind, role, route) => {
         if (!config.browser)
             throw new RefusalError('browser application projection is unavailable');
         const authority = await resolveBrowser();
         return { runtime: authority.runtime, client: authority.client, policy: authority.policy, kind,
-            ...(authority.state ? { state: authority.state } : {}), ...(role ? { role } : {}) };
+            ...(authority.state ? { state: authority.state } : {}), ...(role ? { role } : {}), ...(route ? { route } : {}) };
     };
     const gate = async (request) => {
         if (!authorities.testing || !config.testing)
@@ -690,9 +823,10 @@ function createWorkApplicationComposition(config, authorities) {
             throw new RefusalError(`${repository.identity} at ${repository.root} has no commit yet; commit once there`);
         return [repository.key, head];
     })));
+    const untrackedFiles = async () => new Map(await Promise.all(repositories.map(async (repository) => [repository.key, (await git(repository, ['ls-files', '--others', '--exclude-standard', '-z'])).split('\0').filter(Boolean)])));
     // What changed since the base: committed, staged, unstaged and untracked files, each with its diff
     // or new content. A credential-shaped or declared-instance path is listed but its content is withheld.
-    const changes = async (base) => {
+    const changesWith = async (base, untrackedPaths) => {
         const files = [];
         let budget = MAX_CHANGE_BYTES;
         // What sync generates is cockpit's, not the order's: the paths the ownership manifest lists.
@@ -716,7 +850,7 @@ function createWorkApplicationComposition(config, authorities) {
             const rows = [];
             for (let index = 0; index + 1 < tracked.length; index += 2)
                 rows.push([tracked[index], tracked[index + 1], false]);
-            for (const path of (await git(repository, ['ls-files', '--others', '--exclude-standard', '-z'])).split('\0').filter(Boolean))
+            for (const path of untrackedPaths.get(repository.key))
                 rows.push(['A', path, true]);
             for (const [status, path, untracked] of rows) {
                 if (repository.key === '.' && (excludedRepositoryPath(path, COCKPIT_WRITTEN) || generated.has(path)))
@@ -741,6 +875,40 @@ function createWorkApplicationComposition(config, authorities) {
         }
         return files;
     };
+    // Test weakening since the base, per checkout: committed, staged and unstaged edits of tracked files,
+    // and new untracked test files, which a diff against the base does not list.
+    const weakeningWith = async (base, untracked) => {
+        const patterns = testFilePatterns(config.testing?.testFiles);
+        const isTest = scopeMatcher(patterns.tests);
+        const perRepository = await Promise.all(repositories.map(async (repository) => {
+            const from = base[repository.key] ?? 'HEAD';
+            const diff = await git(repository, ['-c', 'core.quotePath=true', 'diff', '--no-ext-diff', '--no-textconv', '--no-color', '--text', '--find-renames', '--unified=0', from, '--']);
+            const files = parseDiff(diff);
+            for (const path of untracked.get(repository.key)) {
+                if (!isTest(path))
+                    continue;
+                let content;
+                try {
+                    admitRepositoryPath(repository.root, repository.identity, path, repository.sensitivePaths, browserAuthenticationTargets);
+                    content = readBounded(repository.root, path, MAX_DIFF_BYTES).toString('utf8');
+                }
+                catch (error) {
+                    if (error instanceof RefusalError)
+                        continue;
+                    throw error;
+                }
+                files.push({ old: '/dev/null', next: path, hunk: true, removed: false, removedLines: [], renamed: false, deleted: false, added: content.split('\n') });
+            }
+            return weakeningFindings(files, patterns).map(row => ({ ...row, repository: repository.key }));
+        }));
+        return { patterns, findings: perRepository.flat() };
+    };
+    const testWeakening = async (base) => weakeningWith(base, await untrackedFiles());
+    const review = async (base) => {
+        const untracked = await untrackedFiles();
+        const [changed, weakening] = await Promise.all([changesWith(base, untracked), weakeningWith(base, untracked)]);
+        return { changes: changed, weakening };
+    };
     const gradeIndependently = async (subject) => {
         let evaluator;
         try {
@@ -764,13 +932,29 @@ function createWorkApplicationComposition(config, authorities) {
             return { refusal: { code: ENVIRONMENT_CODES.EVALUATOR_ANSWER_INVALID, message: read.problem, fix: 'rerun the command; if the answer is refused again, list another evaluator first in work.evaluators' } };
         return { criteria: read.criteria, evaluator: { tool: result.tool, fallbacks: result.fallbacks } };
     };
+    const containers = async () => {
+        const env = authorities.env;
+        const docker = await resolveDockerExecutable(env);
+        if (docker.state !== 'available')
+            return { state: 'no-docker', reason: docker.reason };
+        const daemon = await selectLocalDockerDaemon(env, 30_000, executeProbe, { command: 'work recover',
+            localOnly: 'a lock holder can be looked for only among the containers on this machine' });
+        if (daemon.kind === 'refusal')
+            return { state: 'unavailable', reason: daemon.diagnostic.message };
+        const listed = await discoverMachineStacks({ executable: docker.value, context: daemon.dockerContext, ...env.DOCKER_HOST === undefined ? {} : { host: env.DOCKER_HOST },
+            cwd: root, env: { PATH: env.PATH ?? '' }, timeoutMs: 30_000 }, executeProbe);
+        if (!listed)
+            return { state: 'unavailable', reason: `the containers cockpit labels could not be listed on Docker context ${daemon.dockerContext}; start Docker, or select the local context that runs cockpit stacks` };
+        return { state: 'listed', context: daemon.dockerContext, containers: listed.resources.filter(row => row.kind === 'container').map(({ id, name, running }) => ({ id, name, running })) };
+    };
     const composition = {
         policy: config.policy, caps: { wip: config.wipCap, attempts: config.attemptCap }, env: authorities.env,
         store: createWorkStore(root), recordedPolicy: () => readRecordedPolicy(root), orderIds, readOrder,
         readCriteriaFile: async (path) => parseCriteriaFile(readBounded(root, path, 65_536)),
         sourceDigests: async (order) => Object.fromEntries(order.criteria.flatMap(row => row.source ? [row.source] : [])
             .map(source => [source, sha256Hex(readSource(source))])),
-        heads, runCheck, changes, evaluate: gradeIndependently, browser, gate,
+        heads, runCheck, evaluate: gradeIndependently, testWeakening, review, browser, gate,
+        ...config.docs ? { docs: config.docs } : {}, decisionRecords, readDocsFile, writeDecisionRecords, containers,
     };
     issuedCompositions.add(composition);
     return composition;
@@ -970,14 +1154,22 @@ export async function createConfiguredWorkApplicationComposition(input, options
                         namespace: browserAuthority.namespace, stackId: loaded.result.stackId, ownerId: record.value.holderId,
                     } } : {}) };
         };
-        const configuredSiblingsRoot = resolve(config.cockpitRoot, config.siblingsRoot);
+        // Work orders and gates read each sibling where `cockpit use` serves it, as the stack does.
+        const recorded = await readSiblingCheckouts(config.cockpitRoot);
+        if (recorded.kind !== 'complete')
+            return { kind: 'refusal', reason: `${recorded.diagnostic.code}: ${recorded.diagnostic.message}; ${recorded.diagnostic.fix}` };
+        const served = servedSiblings(config.cockpitRoot, { cockpit: { siblings_root: config.siblingsRoot }, sibling: config.siblings }, recorded.checkouts);
+        const gone = await missingServedCheckout(served);
+        if (gone)
+            return { kind: 'refusal', reason: `${gone.code}: ${gone.message}; ${gone.fix}` };
+        const siblingRoots = config.siblings.map(row => ({ root: servedPath(served, row.slug), environmentFiles: row.environmentFiles }));
         const gateBrowserAuthenticationTargets = new Set((config.browser?.authentication.states ?? []).map(row => resolve(config.cockpitRoot, row.path)));
         const gateRepositories = [
             { identity: config.cockpitName, root: config.cockpitRoot,
-                sensitivePaths: repositoryEnvironmentInstancePaths(config.cockpitRoot, configuredSiblingsRoot, config.siblings),
+                sensitivePaths: repositoryEnvironmentInstancePaths(config.cockpitRoot, siblingRoots),
                 forbiddenTargets: gateBrowserAuthenticationTargets },
-            ...config.siblings.map(row => ({ identity: `siblings/${row.slug}`, root: resolve(configuredSiblingsRoot, row.dir),
-                sensitivePaths: repositoryEnvironmentInstancePaths(resolve(configuredSiblingsRoot, row.dir), configuredSiblingsRoot, config.siblings),
+            ...siblingRoots.map((row, index) => ({ identity: `siblings/${config.siblings[index].slug}`, root: row.root,
+                sensitivePaths: repositoryEnvironmentInstancePaths(row.root, siblingRoots),
                 forbiddenTargets: gateBrowserAuthenticationTargets })),
         ];
         const reads = createReadCommandAdapters({ configPath: captured.configPath, env: captured.env,
@@ -1001,7 +1193,7 @@ export async function createConfiguredWorkApplicationComposition(input, options
             ...(config.browser ? { resolveBrowser } : {}),
             testing: { registry: authority.testing.registry,
                 dependencies: productGateDependencies(config.cockpitRoot, config.source, gateRepositories, declaredEnvironment, executableDirectories), runtime: gateRuntime },
-        });
+        }, served);
         return { kind: 'complete', composition };
     }
     catch (error) {

package/dist/work-orders/contract.d.ts

@@ -34,7 +34,7 @@ export type ParsedFile<T> = Readonly<{
 /** Parses `workorders/<id>.md`; the id the file declares must be the name it is stored under. */
 export declare function parseWorkOrder(bytes: Uint8Array, fileId: string): ParsedFile<WorkOrder>;
 /** The quick-path file `cockpit grade --criteria` reads: front-matter with criteria, and optionally scope and gates. */
-export declare const CriteriaFile: z.ZodObject<{
+declare const CriteriaFile: z.ZodObject<{
     criteria: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         text: z.ZodString;
@@ -51,11 +51,27 @@ export declare const CriteriaFile: z.ZodObject<{
 export declare function parseCriteriaFile(bytes: Uint8Array): ParsedFile<z.infer<typeof CriteriaFile>>;
 /** The digest an acceptance binds: the contract, each cited source's bytes, and the base commits. */
 export declare function workOrderDigest(order: WorkOrder, sources: Readonly<Record<string, string>>, base: Readonly<Record<string, string>>): string;
+/** One part of a contract an amendment changed in a way that may lower the bar, as it read before and after. */
+export type AmendmentReview = Readonly<{
+    field: string;
+    before: string;
+    after: string;
+}>;
+type ContractAmendment = Readonly<{
+    removed: readonly string[];
+    review: readonly AmendmentReview[];
+}>;
 /**
- * The accepted criteria a changed contract removes or rewrites. Adding a criterion strengthens an
- * order; dropping one, or changing what one says or how it is checked, weakens it, and that is never
- * an agent's decision.
+ * How a changed contract moves the bar. Dropping an accepted criterion or gate lowers it in every
+ * reading, so it is `removed`. A rewritten criterion, a widened scope, a dropped or reworded non-goal
+ * or a new objective may lower it or only clarify it: no byte comparison can tell which, so each is
+ * returned for review with its text before and after. Adding a criterion or gate, narrowing scope and
+ * adding a non-goal only raise the bar.
  */
-export declare function criteriaWeakening(accepted: WorkOrder, changed: WorkOrder): readonly string[];
-export declare function scopeMatches(scope: readonly string[], path: string): boolean;
+export declare function contractAmendment(accepted: WorkOrder, changed: WorkOrder): ContractAmendment;
+/** The review fields a `checks` grade enforces: the criteria's checks and the scope. Objective and non-goals bind only where a model grades. */
+export declare const checksBindsField: (field: string) => boolean;
+/** Whether a path falls in `scope`, with each glob compiled once for the many paths a caller tests. */
+export declare function scopeMatcher(scope: readonly string[]): (path: string) => boolean;
+export declare const scopeMatches: (scope: readonly string[], path: string) => boolean;
 export {};

package/dist/work-orders/contract.js

@@ -5,13 +5,12 @@
 import { createHash } from 'node:crypto';
 import { parseDocument } from 'yaml';
 import { z } from 'zod';
+import { REPOSITORY_PATH } from '../repository-path.js';
 // One inert word, never a path or an option: the CLI, the guard and the store each admit it before it names a file.
 export const WORK_ORDER_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 const WORK_ORDER_LIMITS = Object.freeze({ bytes: 65_536, criteria: 12, scope: 64, textBytes: 2_048, arguments: 32, argumentBytes: 2_048 });
 const PRINTABLE = /^[^\x00-\x08\x0b-\x1f\x7f]*$/;
 const text = z.string().trim().min(1).refine(value => Buffer.byteLength(value) <= WORK_ORDER_LIMITS.textBytes && PRINTABLE.test(value), `at most ${WORK_ORDER_LIMITS.textBytes} bytes without control characters`);
-// `path` in the cockpit's own repository, or `<sibling slug>:path` in a sibling; never absolute or climbing.
-const REPOSITORY_PATH = /^(?:[a-z0-9][a-z0-9-]{0,63}:)?(?![/])(?!.*(?:^|[/:])\.\.(?:\/|$))[A-Za-z0-9._@+\-/*?]+$/;
 const repositoryPath = z.string().max(1_024).regex(REPOSITORY_PATH, 'a relative path, optionally <sibling slug>:path, without .. or a leading /');
 const sourcePath = repositoryPath.refine(value => !/[*?]/.test(value), 'a source names one file, without wildcards');
 const argument = z.string().min(1).refine(value => Buffer.byteLength(value) <= WORK_ORDER_LIMITS.argumentBytes && !/[\x00-\x1f\x7f]/.test(value), 'a bounded argument without control characters');
@@ -77,7 +76,7 @@ export function parseWorkOrder(bytes, fileId) {
     return { ok: true, value: parsed.data };
 }
 /** The quick-path file `cockpit grade --criteria` reads: front-matter with criteria, and optionally scope and gates. */
-export const CriteriaFile = z.object({ criteria: Criteria, scope: z.array(repositoryPath).max(WORK_ORDER_LIMITS.scope).default([]),
+const CriteriaFile = z.object({ criteria: Criteria, scope: z.array(repositoryPath).max(WORK_ORDER_LIMITS.scope).default([]),
     gates: z.array(z.string().regex(/^[a-z][a-z0-9-]{0,63}$/)).max(16).default([]), objective: text.optional() }).strict();
 export function parseCriteriaFile(bytes) {
     const read = frontMatter(bytes);
@@ -97,26 +96,45 @@ function canonical(value) {
 export function workOrderDigest(order, sources, base) {
     return createHash('sha256').update(JSON.stringify(canonical({ order, sources, base }))).digest('hex');
 }
+const criterionText = (row) => `${row.text}${row.check ? ` [check: ${JSON.stringify(row.check)}]` : ''}${row.source ? ` [source: ${row.source}]` : ''}`;
 /**
- * The accepted criteria a changed contract removes or rewrites. Adding a criterion strengthens an
- * order; dropping one, or changing what one says or how it is checked, weakens it, and that is never
- * an agent's decision.
+ * How a changed contract moves the bar. Dropping an accepted criterion or gate lowers it in every
+ * reading, so it is `removed`. A rewritten criterion, a widened scope, a dropped or reworded non-goal
+ * or a new objective may lower it or only clarify it: no byte comparison can tell which, so each is
+ * returned for review with its text before and after. Adding a criterion or gate, narrowing scope and
+ * adding a non-goal only raise the bar.
  */
-export function criteriaWeakening(accepted, changed) {
-    return accepted.criteria.flatMap(before => {
+export function contractAmendment(accepted, changed) {
+    const removed = [...accepted.criteria.filter(before => !changed.criteria.some(row => row.id === before.id)).map(row => `${row.id} is removed`),
+        ...accepted.gates.filter(gate => !changed.gates.includes(gate)).map(gate => `gate ${gate} is removed`)];
+    const review = accepted.criteria.flatMap(before => {
         const after = changed.criteria.find(row => row.id === before.id);
-        if (!after)
-            return [`${before.id} is removed`];
-        return JSON.stringify(canonical(after)) === JSON.stringify(canonical(before)) ? [] : [`${before.id} is rewritten`];
+        return after && JSON.stringify(canonical(after)) !== JSON.stringify(canonical(before))
+            ? [{ field: `criteria.${before.id}`, before: criterionText(before), after: criterionText(after) }] : [];
     });
+    if (changed.scope.some(entry => !accepted.scope.includes(entry)))
+        review.push({ field: 'scope', before: accepted.scope.join(', '), after: changed.scope.join(', ') });
+    if (accepted.non_goals.some(goal => !changed.non_goals.includes(goal)))
+        review.push({ field: 'non_goals', before: accepted.non_goals.join('; '), after: changed.non_goals.join('; ') });
+    if (accepted.objective !== changed.objective)
+        review.push({ field: 'objective', before: accepted.objective, after: changed.objective });
+    return { removed, review };
 }
+/** The review fields a `checks` grade enforces: the criteria's checks and the scope. Objective and non-goals bind only where a model grades. */
+export const checksBindsField = (field) => field === 'scope' || field.startsWith('criteria.');
 // `**` crosses directories, `*` and `?` stay within one; a plain entry also covers what is below it.
-export function scopeMatches(scope, path) {
-    return scope.some(entry => {
-        if (!/[*?]/.test(entry))
-            return path === entry || path.startsWith(`${entry.replace(/\/$/, '')}/`);
+/** Whether a path falls in `scope`, with each glob compiled once for the many paths a caller tests. */
+export function scopeMatcher(scope) {
+    const tests = scope.map((entry) => {
+        if (!/[*?]/.test(entry)) {
+            const directory = `${entry.replace(/\/$/, '')}/`;
+            return path => path === entry || path.startsWith(directory);
+        }
         const pattern = entry.split(/(\*\*\/?|\*|\?)/).map(part => part === '**' || part === '**/' ? '(?:.*/)?' + (part === '**' ? '.*' : '')
             : part === '*' ? '[^/]*' : part === '?' ? '[^/]' : part.replace(/[.+^${}()|[\]\\]/g, '\\$&')).join('');
-        return new RegExp(`^${pattern}$`).test(path);
+        const compiled = new RegExp(`^${pattern}$`);
+        return path => compiled.test(path);
     });
+    return path => tests.some(test => test(path));
 }
+export const scopeMatches = (scope, path) => scopeMatcher(scope)(path);

package/dist/work-orders/decisions.d.ts

@@ -0,0 +1,23 @@
+type RecordName = Readonly<{
+    name: string;
+    number?: string;
+}>;
+/** The next record's file name: the next free number, at least four digits wide, unless the directory names records by date. */
+export declare function nextRecordName(existing: readonly string[], title: string, today: string): RecordName;
+/** A single-line title, safe inside a heading and a Markdown link label. */
+export declare function recordTitle(text: string): string;
+export declare function scaffoldRecord(input: Readonly<{
+    title: string;
+    number?: string;
+    workOrder: string;
+    supersedes?: string;
+}>): string;
+export declare const holdsPlaceholders: (text: string) => boolean;
+/** The work orders a record cites, from a `Work order:` line or a `work_order:` front-matter field. */
+export declare function citedOrders(text: string): readonly string[];
+/**
+ * Whether a record names a path inside `scope`. A path-like word is one with a slash; a record kept
+ * in a sibling names that sibling's paths without its prefix, so `prefix` qualifies them.
+ */
+export declare function namesScope(text: string, scope: readonly string[], prefix: string): boolean;
+export {};

package/dist/work-orders/decisions.js

@@ -0,0 +1,55 @@
+// Owns the decision records a work order cites, read and written as text: how a new record is named,
+// the template cockpit scaffolds, whether a record still holds that template's placeholders, which
+// order it cites, and which paths it names. The integrity of the whole directory (duplicate numbers,
+// an index that misses a file) is the docs check's; this module reads only what an order needs.
+import { isDatedRecordName, recordNumber } from '../docs/decision-record.js';
+import { splitRepositoryPath } from '../repository-path.js';
+import { scopeMatcher, WORK_ORDER_ID } from './contract.js';
+// Every placeholder the template writes carries this, so a record nobody filled in is detectable.
+const PLACEHOLDER = 'cockpit: replace this';
+/** The next record's file name: the next free number, at least four digits wide, unless the directory names records by date. */
+export function nextRecordName(existing, title, today) {
+    const records = existing.filter(name => name.endsWith('.md'));
+    const numbers = records.flatMap(name => recordNumber(name) ?? []);
+    const slug = title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 64).replace(/-+$/, '') || 'decision';
+    if (!numbers.length && records.some(isDatedRecordName)) {
+        // Two decisions with one title on one day would otherwise share a name.
+        let name = `${today}-${slug}.md`;
+        for (let suffix = 2; records.includes(name); suffix++)
+            name = `${today}-${slug}-${suffix}.md`;
+        return { name };
+    }
+    const next = numbers.reduce((max, value) => Math.max(max, Number(value)), 0) + 1;
+    const number = String(next).padStart(Math.max(4, ...numbers.map(value => value.length)), '0');
+    return { name: `${number}-${slug}.md`, number };
+}
+/** A single-line title, safe inside a heading and a Markdown link label. */
+export function recordTitle(text) {
+    return text.replace(/\s+/g, ' ').trim().replace(/[[\]]/g, '');
+}
+export function scaffoldRecord(input) {
+    return [`# ${input.number ? `${input.number}. ` : ''}${input.title}`, '', 'Status: accepted', `Work order: ${input.workOrder}`,
+        ...input.supersedes ? [`Supersedes: ${input.supersedes}`] : [], '',
+        '## Context', '', `<!-- ${PLACEHOLDER} with what made a decision necessary. -->`, '',
+        '## Decision', '', `<!-- ${PLACEHOLDER} with what was decided. -->`, '',
+        '## Consequences', '', `<!-- ${PLACEHOLDER} with what becomes easier or harder because of it. -->`, ''].join('\n');
+}
+export const holdsPlaceholders = (text) => text.includes(PLACEHOLDER);
+/** The work orders a record cites, from a `Work order:` line or a `work_order:` front-matter field. */
+export function citedOrders(text) {
+    return [...text.matchAll(/^\**work[ _-]order\**:\**[ \t]*(.+)$/gim)]
+        .flatMap(match => match[1].split(/[\s,`]+/)).filter(id => id && WORK_ORDER_ID.test(id));
+}
+/**
+ * Whether a record names a path inside `scope`. A path-like word is one with a slash; a record kept
+ * in a sibling names that sibling's paths without its prefix, so `prefix` qualifies them.
+ */
+export function namesScope(text, scope, prefix) {
+    const inScope = scopeMatcher(scope);
+    for (const match of text.matchAll(/(?:^|[\s`(<"'[])((?:[a-z0-9][a-z0-9-]{0,63}:)?[A-Za-z0-9._@+-]+(?:\/[A-Za-z0-9._@+-]*)+)/g)) {
+        const path = match[1].replace(/^\.\//, '').replace(/[.,;:]+$/, '');
+        if (inScope(splitRepositoryPath(path).slug === undefined ? `${prefix}${path}` : path))
+            return true;
+    }
+    return false;
+}