@b00dea/cockpit 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,77 @@
+import { z } from 'zod';
+export declare const WORK_ORDER_ID: RegExp;
+declare const Check: z.ZodUnion<readonly [z.ZodObject<{
+    gate: z.ZodString;
+    select: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodArray<z.ZodString>]>;
+export type WorkOrderCheck = z.infer<typeof Check>;
+export declare const WorkOrderFrontMatter: z.ZodObject<{
+    id: z.ZodString;
+    objective: z.ZodString;
+    scope: z.ZodArray<z.ZodString>;
+    depends_on: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    gates: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    criteria: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        text: z.ZodString;
+        check: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+            gate: z.ZodString;
+            select: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>, z.ZodArray<z.ZodString>]>>;
+        source: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    non_goals: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type WorkOrder = z.infer<typeof WorkOrderFrontMatter>;
+export type WorkOrderCriterion = WorkOrder['criteria'][number];
+export type ParsedFile<T> = Readonly<{
+    ok: true;
+    value: T;
+}> | Readonly<{
+    ok: false;
+    problems: readonly string[];
+}>;
+/** 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. */
+declare const CriteriaFile: z.ZodObject<{
+    criteria: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        text: z.ZodString;
+        check: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+            gate: z.ZodString;
+            select: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>, z.ZodArray<z.ZodString>]>>;
+        source: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    scope: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    gates: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    objective: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+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[];
+}>;
+/**
+ * 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 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

@@ -0,0 +1,140 @@
+// Owns the work-order file: `workorders/<id>.md`, whose YAML front-matter is the whole contract an
+// order is accepted, checked and graded against, and whose Markdown body is free notes cockpit never
+// reads. One schema validates the front-matter; the digest binds it with the bytes of every source a
+// criterion cites and the commit each repository stood at when the order was accepted.
+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`);
+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');
+const GateCheck = z.object({
+    gate: z.string().regex(/^[a-z][a-z0-9-]{0,63}$/, 'a declared [testing] gate id'),
+    // A selected value that starts with `-` would reach the product's tool as an option of its own.
+    select: z.string().max(4_096).regex(/^(?:spec|file|test|route):[^-]/, 'spec|file|test|route:<value>').optional(),
+}).strict();
+const Check = z.union([GateCheck, z.array(argument).min(1).max(WORK_ORDER_LIMITS.arguments)]);
+const Criterion = z.object({
+    id: z.string().regex(/^[A-Za-z][A-Za-z0-9_-]{0,31}$/, 'a short identifier such as AC1'),
+    text,
+    check: Check.optional(),
+    source: sourcePath.optional(),
+}).strict();
+const Criteria = z.array(Criterion).min(1).max(WORK_ORDER_LIMITS.criteria)
+    .refine(rows => new Set(rows.map(row => row.id)).size === rows.length, 'each criterion id is used once');
+export const WorkOrderFrontMatter = z.object({
+    id: z.string().regex(WORK_ORDER_ID, 'letters, digits, dot, underscore or hyphen, at most 128'),
+    objective: text,
+    scope: z.array(repositoryPath).min(1).max(WORK_ORDER_LIMITS.scope).describe('Paths and globs the work may change.'),
+    depends_on: z.array(z.string().regex(WORK_ORDER_ID)).max(32).default([]),
+    gates: z.array(z.string().regex(/^[a-z][a-z0-9-]{0,63}$/)).max(16).default([]).describe('Declared [testing] gates that must pass at work check.'),
+    criteria: Criteria,
+    non_goals: z.array(text).max(32).default([]),
+}).strict();
+function frontMatter(bytes) {
+    if (bytes.byteLength > WORK_ORDER_LIMITS.bytes)
+        return { ok: false, problems: [`the file exceeds ${WORK_ORDER_LIMITS.bytes} bytes`] };
+    let source;
+    try {
+        source = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    }
+    catch (error) {
+        if (!(error instanceof TypeError))
+            throw error;
+        return { ok: false, problems: ['the file is not UTF-8'] };
+    }
+    const lines = source.replace(/^/, '').split(/\r?\n/);
+    const end = lines.indexOf('---', 1);
+    if (lines[0] !== '---' || end < 0)
+        return { ok: false, problems: ['the file must start with YAML front-matter between two --- lines'] };
+    const document = parseDocument(lines.slice(1, end).join('\n'), { uniqueKeys: true, prettyErrors: false });
+    if (document.errors.length)
+        return { ok: false, problems: document.errors.map(error => `front-matter is not YAML: ${error.message.split('\n')[0]}`) };
+    return { ok: true, value: document.toJS({ maxAliasCount: 0 }) };
+}
+function issues(error) {
+    return error.issues.map(issue => `${issue.path.length ? issue.path.join('.') : 'front-matter'}: ${issue.message}`);
+}
+/** Parses `workorders/<id>.md`; the id the file declares must be the name it is stored under. */
+export function parseWorkOrder(bytes, fileId) {
+    const read = frontMatter(bytes);
+    if (!read.ok)
+        return read;
+    const parsed = WorkOrderFrontMatter.safeParse(read.value);
+    if (!parsed.success)
+        return { ok: false, problems: issues(parsed.error) };
+    if (parsed.data.id !== fileId)
+        return { ok: false, problems: [`id: the file workorders/${fileId}.md declares id ${parsed.data.id}; they must match`] };
+    if (parsed.data.depends_on.includes(parsed.data.id))
+        return { ok: false, problems: ['depends_on: an order cannot depend on itself'] };
+    return { ok: true, value: parsed.data };
+}
+/** The quick-path file `cockpit grade --criteria` reads: front-matter with criteria, and optionally scope and gates. */
+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);
+    if (!read.ok)
+        return read;
+    const parsed = CriteriaFile.safeParse(read.value);
+    return parsed.success ? { ok: true, value: parsed.data } : { ok: false, problems: issues(parsed.error) };
+}
+function canonical(value) {
+    if (Array.isArray(value))
+        return value.map(canonical);
+    if (value === null || typeof value !== 'object')
+        return value;
+    return Object.fromEntries(Object.keys(value).sort().map(key => [key, canonical(value[key])]));
+}
+/** The digest an acceptance binds: the contract, each cited source's bytes, and the base commits. */
+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}]` : ''}`;
+/**
+ * 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 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);
+        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.
+/** 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('');
+        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;
+}

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

@@ -0,0 +1,207 @@
+import { z } from 'zod';
+export declare const WORK_RECORD_DIRECTORY = ".cockpit/work-orders";
+declare const CheckResult: z.ZodObject<{
+    criterion: z.ZodString;
+    kind: z.ZodEnum<{
+        argv: "argv";
+        gate: "gate";
+    }>;
+    passed: z.ZodBoolean;
+    outcome: z.ZodString;
+    output: z.ZodString;
+}, z.core.$strict>;
+export type CheckResult = z.infer<typeof CheckResult>;
+export declare const WorkRecord: z.ZodObject<{
+    format: z.ZodLiteral<"cockpit-work-order/v1">;
+    id: z.ZodString;
+    state: z.ZodEnum<{
+        abandoned: "abandoned";
+        accepted: "accepted";
+        checked: "checked";
+        done: "done";
+        graded: "graded";
+        partial: "partial";
+    }>;
+    accepted: z.ZodObject<{
+        at: z.ZodString;
+        by: z.ZodEnum<{
+            agent: "agent";
+            ci: "ci";
+            person: "person";
+        }>;
+        digest: z.ZodString;
+        order: z.ZodObject<{
+            id: z.ZodString;
+            objective: z.ZodString;
+            scope: z.ZodArray<z.ZodString>;
+            depends_on: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            gates: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            criteria: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                text: z.ZodString;
+                check: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+                    gate: z.ZodString;
+                    select: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>, z.ZodArray<z.ZodString>]>>;
+                source: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
+            non_goals: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>;
+        sources: z.ZodRecord<z.ZodString, z.ZodString>;
+        base: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$strict>;
+    amendments: z.ZodArray<z.ZodObject<{
+        at: z.ZodString;
+        by: z.ZodEnum<{
+            agent: "agent";
+            ci: "ci";
+            person: "person";
+        }>;
+        from: z.ZodString;
+        to: z.ZodString;
+        weakened: z.ZodArray<z.ZodString>;
+        review: z.ZodArray<z.ZodObject<{
+            field: z.ZodString;
+            before: z.ZodString;
+            after: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    acknowledgements: z.ZodArray<z.ZodObject<{
+        at: z.ZodString;
+        by: z.ZodEnum<{
+            agent: "agent";
+            ci: "ci";
+            person: "person";
+        }>;
+        digest: z.ZodString;
+        findings: z.ZodArray<z.ZodString>;
+        note: z.ZodString;
+    }, z.core.$strict>>;
+    attempts: z.ZodNumber;
+    checks: z.ZodOptional<z.ZodObject<{
+        at: z.ZodString;
+        digest: z.ZodString;
+        results: z.ZodArray<z.ZodObject<{
+            criterion: z.ZodString;
+            kind: z.ZodEnum<{
+                argv: "argv";
+                gate: "gate";
+            }>;
+            passed: z.ZodBoolean;
+            outcome: z.ZodString;
+            output: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    grade: z.ZodOptional<z.ZodObject<{
+        at: z.ZodString;
+        digest: z.ZodString;
+        mode: z.ZodEnum<{
+            checks: "checks";
+            independent: "independent";
+            self: "self";
+        }>;
+        passed: z.ZodBoolean;
+        criteria: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            verdict: z.ZodEnum<{
+                met: "met";
+                unclear: "unclear";
+                unmet: "unmet";
+            }>;
+            note: z.ZodString;
+        }, z.core.$strict>>;
+        outOfScope: z.ZodArray<z.ZodString>;
+        evaluator: z.ZodOptional<z.ZodObject<{
+            tool: z.ZodString;
+            fallbacks: z.ZodArray<z.ZodObject<{
+                tool: z.ZodString;
+                code: z.ZodString;
+                message: z.ZodString;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
+        note: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    amendmentsFailedReview: z.ZodOptional<z.ZodObject<{
+        at: z.ZodString;
+        note: z.ZodString;
+    }, z.core.$strict>>;
+    notes: z.ZodArray<z.ZodObject<{
+        at: z.ZodString;
+        by: z.ZodEnum<{
+            agent: "agent";
+            ci: "ci";
+            person: "person";
+        }>;
+        kind: z.ZodEnum<{
+            answer: "answer";
+            decision: "decision";
+            note: "note";
+            question: "question";
+            resolution: "resolution";
+        }>;
+        text: z.ZodString;
+        answers: z.ZodOptional<z.ZodNumber>;
+        resolves: z.ZodOptional<z.ZodNumber>;
+        record: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    closure: z.ZodOptional<z.ZodObject<{
+        at: z.ZodString;
+        by: z.ZodEnum<{
+            agent: "agent";
+            ci: "ci";
+            person: "person";
+        }>;
+        how: z.ZodEnum<{
+            abandoned: "abandoned";
+            "checks-passed": "checks-passed";
+            graded: "graded";
+            partial: "partial";
+            "self-reported": "self-reported";
+        }>;
+        note: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    recoveries: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        at: z.ZodString;
+        holder: z.ZodString;
+        checked: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type WorkRecord = z.infer<typeof WorkRecord>;
+/** Keeps the end of a command's output, where a runner prints its summary, within the record's bound. */
+export declare function outputTail(value: string): string;
+export interface WorkStore {
+    readonly read: (id: string) => Promise<WorkRecord | undefined>;
+    readonly list: () => Promise<readonly WorkRecord[]>;
+    /** Runs `change` holding the order's lock; it returns the next record, or undefined to write nothing. */
+    readonly update: <T>(id: string, change: (current: WorkRecord | undefined) => Promise<{
+        record?: WorkRecord;
+        value: T;
+    }>) => Promise<T>;
+    /** Names a lock's holder and, with `apply`, removes the lock once the holder is shown gone, recording what was checked. */
+    readonly recover: (id: string, apply: boolean, containers: () => Promise<ContainerEvidence>) => Promise<LockRecovery>;
+}
+/** The containers cockpit labels on this machine's Docker daemon, which a process probe cannot look inside. */
+export type ContainerEvidence = Readonly<{
+    state: 'listed';
+    context: string;
+    containers: readonly Readonly<{
+        id: string;
+        name: string;
+        running: boolean;
+    }>[];
+}> | Readonly<{
+    state: 'no-docker';
+    reason: string;
+}> | Readonly<{
+    state: 'unavailable';
+    reason: string;
+}>;
+type LockRecovery = Readonly<{
+    id: string;
+    lock: 'none' | 'live' | 'unknown' | 'dead' | 'removed';
+    holder?: string;
+    checked?: readonly string[];
+    recorded?: boolean;
+}>;
+export declare function createWorkStore(root: string): WorkStore;
+export {};