wicked-crew 0.7.46 → 0.7.48

package/dist/api/policy-landing.js

@@ -0,0 +1,174 @@
+/**
+ * THE policy-rule landing (DES-MEM-FACETED-001 §5.2; DC-S3 probe + read-back; DC-S4a one path).
+ *
+ * `POST /proposals/:id/approve` (an ordinary policy proposal) and the decision landing
+ * (`decisions/land.ts remember()`) both end here, so the probe, the read-back and the audit cannot
+ * drift between them:
+ *
+ * 1. probe: a project-scoped (or superseding) rule on an engine without project rules fails loud
+ *    and writes nothing — the engine would accept the fields and drop them, landing it everywhere;
+ * 2. upsert through the single-writer actor;
+ * 3. read-back: the stored rule must still carry `targets.project`, the proposal ref and every
+ *    `supersedes` id; a mismatch RETIRES the just-written rule (retire, never delete) and fails loud;
+ * 4. audit `governance.rule.upserted` with the caller's `via`.
+ *
+ * Failures are returned in-band (`outcome:"failed"`, the crew#388 anti-silent-loss doctrine).
+ */
+import { STEERING_TYPE_VALUES, STEERING_TYPES } from './governance-steering.js';
+const V = '/api/v1';
+/**
+ * Map an APPROVED policy proposal (estate `proposal.approve` → `handed_off`) into a steering
+ * ConformanceRule (DES-MEM-FACETED-001 §5.2). A policy proposal's `kind_type` is
+ * `policy:<steering_type>` and its `payload` is `{ rule, severity }`; estate writes NOTHING for it
+ * (the AW-11 "no rules.write on estate" invariant) and hands the payload back for crew — the ONE
+ * governed rules-write path — to land. Returns the rule to upsert plus the resolved steering type,
+ * or a loud `error` string when the proposal cannot be shaped into a valid rule (a malformed
+ * `kind_type` / missing `rule` / out-of-enum `severity`) — the caller reports it as a failed
+ * landing, never a silent drop (the crew#388 anti-silent-loss doctrine).
+ *
+ * The rule id is DETERMINISTIC (`proposal:<id>`) so a re-driven landing UPSERTS the same rule
+ * (idempotent) instead of minting a duplicate; it sits OUTSIDE the reserved `PAT-/POL-` namespace,
+ * which UI/chat/proposal-authored rules are free to do (INV-C1). The rule carries NO `effect`
+ * (recall-only — exactly what `{rule, severity}` supports: an enforcement rule would need a
+ * non-blank `applies_to`, which the payload does not carry, and INV-S3 fails such a rule closed).
+ * `steering_type` is validated against the vocabulary here so the engine's INV-S1 never rejects it
+ * as an unknown page.
+ */
+export function policyProposalToRule(proposalId, kindType, payload, facets) {
+    const steeringType = kindType.startsWith('policy:') ? kindType.slice('policy:'.length) : '';
+    if (!STEERING_TYPES.has(steeringType)) {
+        return {
+            error: `the approved proposal's kind_type ${JSON.stringify(kindType)} does not name a steering ` +
+                `type — expected \`policy:<${STEERING_TYPE_VALUES.join('|')}>\``,
+        };
+    }
+    const body = typeof payload === 'object' && payload !== null && !Array.isArray(payload)
+        ? payload
+        : {};
+    const statement = typeof body['rule'] === 'string' ? body['rule'].trim() : '';
+    if (statement === '') {
+        return {
+            error: 'the approved policy proposal payload has no `rule` string to make a rule statement from',
+        };
+    }
+    const rawSeverity = body['severity'];
+    // Normalize common LLM drift before the enum check: a model naturally writes the English word
+    // "warning", but the engine's enum is the short "warn" (info/error/critical are already the
+    // natural words). Tolerate case/whitespace too. A capture worker that says "warning" must still
+    // land its policy — otherwise every derived policy at the middle band silently fails to land.
+    const normSeverity = typeof rawSeverity === 'string'
+        ? (() => {
+            const s = rawSeverity.trim().toLowerCase();
+            return s === 'warning' ? 'warn' : s;
+        })()
+        : rawSeverity;
+    const severity = normSeverity === 'info' || normSeverity === 'warn' || normSeverity === 'error' || normSeverity === 'critical'
+        ? normSeverity
+        : undefined;
+    if (rawSeverity !== undefined && severity === undefined) {
+        return {
+            error: `the approved policy proposal payload has an invalid severity ${JSON.stringify(rawSeverity)} — ` +
+                'expected info|warn|error|critical (or the natural "warning" for warn)',
+        };
+    }
+    const language = facets?.['language'];
+    const project = facets?.['project'];
+    const targets = {};
+    if (typeof language === 'string' && language !== '')
+        targets.language = language;
+    // DC-S3: the `project` facet is the rule's `targets.project` — a project decision lands scoped to
+    // that project, never everywhere (E3). The caller probes the engine and reads the rule back.
+    if (typeof project === 'string' && project !== '')
+        targets.project = project;
+    const rule = {
+        id: `proposal:${proposalId}`,
+        rule_type: 'policy',
+        statement,
+        // A policy proposal SHOULD carry severity; a missing one defaults to `warn` (the middle band)
+        // rather than failing the landing, but a present-but-garbage one fails loud above.
+        severity: severity ?? 'warn',
+        // REQUIRED engine-side (f32, no serde default, INV-C2 `[0,1]`); the payload carries none, so a
+        // fixed authority — the same 0.8 the steering-author landing defaults to.
+        confidence: 0.8,
+        // `language` and `project` map onto the engine's Targets; a `repo` facet has no rule slot.
+        targets,
+        // The landed rule names the proposal it came from (DC-S3), the same id it is keyed on.
+        provenance: { source: 'proposal', ref: `proposal:${proposalId}`, source_kinds: [] },
+        steering_type: steeringType,
+    };
+    return { rule, steeringType: steeringType };
+}
+function message(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+export async function landPolicyRule(deps, built, actor, detail) {
+    const { adapter, audit } = deps;
+    const project = built.rule.targets.project;
+    const supersedes = built.rule.supersedes ?? [];
+    if ((project !== undefined || supersedes.length > 0) && !adapter.projectRulesSupported()) {
+        return {
+            outcome: 'failed',
+            error: project !== undefined
+                ? `the approved policy proposal is scoped to project \`${project}\`, but the installed engine ` +
+                    'cannot keep a rule\'s project and would land it everywhere; upgrade wicked-core-ts (>= 0.7.35)'
+                : 'the rule replaces other rules (`supersedes`), but the installed engine would drop the field; ' +
+                    'upgrade wicked-core-ts (>= 0.7.35)',
+        };
+    }
+    try {
+        await adapter.upsertConformanceRule(built.rule);
+    }
+    catch (err) {
+        return {
+            outcome: 'failed',
+            error: `the store refused the steering rule derived from the approved policy proposal: ${message(err)}`,
+        };
+    }
+    let lost;
+    try {
+        const stored = await adapter.readConformanceRule(built.rule.id);
+        const storedSupersedes = new Set(stored?.supersedes ?? []);
+        const missing = supersedes.filter((s) => !storedSupersedes.has(s));
+        lost =
+            stored === null
+                ? 'the rule is not in the store'
+                : (stored.targets?.project ?? undefined) !== project
+                    ? `targets.project reads back ${JSON.stringify(stored.targets?.project ?? null)}, not ${JSON.stringify(project ?? null)}`
+                    : stored.provenance?.ref !== built.rule.provenance.ref
+                        ? `provenance.ref reads back ${JSON.stringify(stored.provenance?.ref ?? null)}, not ${JSON.stringify(built.rule.provenance.ref)}`
+                        : missing.length > 0
+                            ? `supersedes reads back without ${JSON.stringify(missing)}`
+                            : null;
+    }
+    catch (err) {
+        lost = `the rule could not be read back (${message(err)})`;
+    }
+    if (lost !== null) {
+        let retired;
+        try {
+            await adapter.retireConformanceRule(built.rule.id);
+            retired = `rule ${built.rule.id} was retired`;
+        }
+        catch (err) {
+            retired = `retiring rule ${built.rule.id} FAILED (${message(err)}); retire it by hand via DELETE ${V}/governance/rules/${built.rule.id}`;
+        }
+        return { outcome: 'failed', error: `the engine did not keep the landed rule as written: ${lost}; ${retired}` };
+    }
+    audit.record('governance.rule.upserted', actor, {
+        detail: {
+            id: built.rule.id,
+            source: 'proposal',
+            steeringType: built.steeringType,
+            ...detail,
+            ...(project !== undefined ? { project } : {}),
+            ...(supersedes.length > 0 ? { supersedes } : {}),
+        },
+    });
+    return {
+        outcome: 'landed',
+        ruleId: built.rule.id,
+        steering_type: built.steeringType,
+        ...(project !== undefined ? { project } : {}),
+    };
+}
+//# sourceMappingURL=policy-landing.js.map

package/dist/api/policy-landing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-landing.js","sourceRoot":"","sources":["../../src/api/policy-landing.ts"],"names":[],"mappings":"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"}

package/dist/api/recording.d.ts

@@ -0,0 +1,228 @@
+/**
+ * The recording views (DES-walkthrough-proof §4.10: `api/demo.ts` renamed `api/recording.ts`) — the
+ * Demo experience and the walkthrough, which share `parseChapters`, `parseMarkers` and
+ * `containedPath`.
+ *
+ * ## Demo
+ *
+ * The Demo experience (wicked-studio#373, migration M9b): a demo of a local app, made by a governed
+ * run of the built-in `demo` preset — the wicked-garden demo skill's plan → record → review.
+ *
+ *   POST /projects/:id/demo        mints the run's DEMO ROOT (a per-run directory on the daemon host),
+ *                                  writes the brief there, and launches `demo` THROUGH `POST /runs`
+ *                                  (one launch path), with the root as the run's only extra write root.
+ *   GET  /runs/:id/demo            what studio shows: the stage, the presenter script and chapter list
+ *                                  (the plan gate), per-chapter record progress, the contact sheets and
+ *                                  the reviewer's verdicts (the review gate), and the chaptered MP4.
+ *   GET  /runs/:id/demo/file       one file of the root (a contact sheet, the MP4 — with Range).
+ *   PUT  /runs/:id/demo/script     the presenter's edit of `script.md` while the plan gate is open.
+ *   POST /runs/:id/demo/export     a GIF (`demo-video/demo.gif`) or a poster frame (`demo-video/poster.jpg`)
+ *                                  of the stitched MP4, encoded by ffmpeg with an ASYNC spawn and a
+ *                                  timeout (EP-C3): the daemon keeps answering while it encodes.
+ *
+ * The gates are the run's ordinary gates (`POST /runs/:id/gate`): approve, or `request_changes` with a
+ * note — at the plan gate it re-runs `plan`, at the review gate it rewinds to `record` (re-record one
+ * chapter). Nothing here decides a gate.
+ *
+ * Every file is read from the root the daemon minted for THIS run id, never from a path a caller or a
+ * worker names: `path` is resolved inside it, symlinks included, and only the deliverable types studio
+ * renders are served.
+ *
+ * ## Walkthrough (WT-W1)
+ *
+ * Every repo-bound run gets an EVIDENCE ROOT (`walkthroughRootDir`, minted by `CoreAdapter.launchRun`
+ * and persisted by the engine as `session.evidence_root`). Under it, `author/<plan step>/` is the
+ * walkthrough author's write dir and `<review step>/` is the PROOF ROOT only the jailed
+ * `walkthrough_review` Tool writes.
+ *
+ *   GET  /runs/:id/walkthrough?step=             the `WalkthroughView` of the newest (or the named) pair.
+ *   GET  /runs/:id/walkthrough/file?step=&path=  one file of that pair's proof root (Range for the MP4).
+ *
+ * What the view reads from a proof root (the recorder's files, DES-walkthrough-proof §4.4):
+ *
+ *   result.json      `{overall, cause?, reason?, tree?, chapters: [{key, title?, verdict, takes?,
+ *                    failed_at_sec?, failed_frame?, proves?, legs?, checks?: [{id, kind, sentence,
+ *                    passed, at_sec, evidence?, vault_entry?, detail?}]}]}` — the engine itself writes
+ *                    `{overall: INCONCLUSIVE, cause, reason, chapters: []}` when it cannot record.
+ *   progress.json    `{state: 'starting_app' | 'recording' | 'judging', chapter?}` while it runs.
+ *   chapters.json    the chapter list (the demo shape), before the judge has written verdicts.
+ *   demo-video/      `demo.mp4`, `poster.jpg`, `chapters.md` (markers), `segments/<key>/segment.mp4`.
+ *
+ * The proof root is read only when it is a plain directory directly under the evidence root (a link
+ * planted at the step path is never followed — the engine's `check_proof_root` rule), and every file
+ * inside it through `containedPath`.
+ */
+import type { FastifyInstance } from 'fastify';
+import { z } from 'zod';
+import type { DemoChapter, DemoExportFormat, DemoFinding, DemoMarker, DemoStage, DemoView, WalkthroughView } from 'wicked-crew-api-types';
+import type { CoreAdapter } from '../core/adapter.js';
+import type { SessionView, WorkUnit } from '../core/types.js';
+import type { AuditLog } from './audit.js';
+import { type WalkthroughGate } from '../qe/walkthrough-acceptance.js';
+import type { WalkthroughStepState } from 'wicked-crew-api-types';
+/** The preset a demo run launches (wicked-core `builtin_presets`). */
+export declare const DEMO_PRESET = "demo";
+/** The biggest script studio shows or accepts back: a presenter script is prose. */
+export declare const DEMO_SCRIPT_MAX_BYTES: number;
+/** Where a demo run's files live: one directory per run, outside every sandbox and state home. */
+export declare function demoRootDir(runId: string): string;
+/**
+ * The demo root of each demo launch in flight, keyed by the run id the demo route minted. `POST /runs`
+ * takes no write roots from its body; it reads this in-process entry, so the root is never something a
+ * caller can ask for (the capture route's pattern).
+ */
+export declare const demoLaunchRoots: Map<string, string>;
+export declare const DemoLaunchSchema: z.ZodObject<{
+    url: z.ZodEffects<z.ZodString, string, string>;
+    audience: z.ZodString;
+    show: z.ZodString;
+    clisJson: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    url: string;
+    audience: string;
+    show: string;
+    clisJson?: string | undefined;
+}, {
+    url: string;
+    audience: string;
+    show: string;
+    clisJson?: string | undefined;
+}>;
+export declare const DemoScriptSchema: z.ZodObject<{
+    content: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    content: string;
+}, {
+    content: string;
+}>;
+export declare const DemoExportSchema: z.ZodEffects<z.ZodObject<{
+    format: z.ZodEnum<["gif", "poster"]>;
+    /** The poster's frame, in seconds from the start. Poster only. */
+    atSec: z.ZodOptional<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    format: "gif" | "poster";
+    atSec?: number | undefined;
+}, {
+    format: "gif" | "poster";
+    atSec?: number | undefined;
+}>, {
+    format: "gif" | "poster";
+    atSec?: number | undefined;
+}, {
+    format: "gif" | "poster";
+    atSec?: number | undefined;
+}>;
+/**
+ * How long one encode may run before it is killed (EP-C3). A GIF re-encodes the whole video (the bound
+ * interactive's encoder uses); a poster decodes one frame. Mutable only so a test can shorten it.
+ */
+export declare const DEMO_EXPORT_TIMEOUT_MS: Record<DemoExportFormat, number>;
+/** Interactive's GIF filter (`src/service/demo.js` `ffmpegGifEncoder`): two-pass palette so colours do not band, 10 fps, 720 px. */
+export declare const DEMO_GIF_FILTER = "fps=10,scale=720:-1:flags=lanczos,split[s0][s1];[s0]palettegen=stats_mode=diff[p];[s1][p]paletteuse=dither=bayer:bayer_scale=3";
+export declare const DEMO_FFMPEG_HINT = "install ffmpeg (e.g. `brew install ffmpeg` / `apt install ffmpeg`) on the daemon host, or set WICKED_FFMPEG to its path";
+type FfmpegOutcome = {
+    kind: 'ok';
+} | {
+    kind: 'missing';
+} | {
+    kind: 'timeout';
+} | {
+    kind: 'failed';
+    code: number | null;
+    stderr: string;
+};
+/**
+ * Run ffmpeg without blocking the event loop: an async `spawn`, its stderr tail kept for the error,
+ * SIGKILL past `timeoutMs`. Never `spawnSync` (review N6: a 180 s synchronous encode would stall
+ * every route the daemon serves, `/health` included).
+ */
+export declare function runFfmpeg(args: string[], timeoutMs: number): Promise<FfmpegOutcome>;
+/** The brief the demo run reads (the problem statement stays one short line: worker prompts are capped). */
+export declare function demoBrief(root: string, b: {
+    url: string;
+    audience: string;
+    show: string;
+}): string;
+/** A demo run: launched from the `demo` preset — read off the engine's plan state, or, before the
+ *  launch is scored and `team_plan` exists, off the run's identity (resolved from the launch record). */
+export declare function isDemoRun(view: SessionView): boolean;
+/** Where the run stands, in the Demo experience's words. */
+export declare function demoStage(view: SessionView): DemoStage;
+/** `chapters.json` → the chapter list, or `[]` when it is missing or not the plan's shape. */
+export declare function parseChapters(raw: string | null): Omit<DemoChapter, 'recorded'>[];
+/** `chapters.md` (record.mjs's `| m:ss | Title |` table) → the MP4's chapter markers. */
+export declare function parseMarkers(raw: string | null): DemoMarker[];
+/** The reviewer's output → its verdict block (the LAST fenced ```json block), or nothing. */
+export declare function parseReview(output: string | null): {
+    verdict: 'accept' | 'changes' | null;
+    findings: DemoFinding[];
+};
+/** Everything studio renders for a demo run, read from its root and its units. */
+export declare function demoView(adapter: CoreAdapter, view: SessionView): Promise<DemoView>;
+/** A single `Range: bytes=a-b` → the inclusive span, `null` for no header, `'bad'` for one we cannot serve. */
+export declare function parseRange(header: string | undefined, size: number): {
+    start: number;
+    end: number;
+} | null | 'bad';
+export declare function registerDemoRoutes(app: FastifyInstance, adapter: CoreAdapter): void;
+/** The catalog id of the walkthrough author (an evaluator agent step). */
+export declare const WALKTHROUGH_PLAN_CATALOG = "walkthrough_plan";
+/** The catalog id of the walkthrough recorder (the jailed, engine-run Tool step). */
+export declare const WALKTHROUGH_REVIEW_CATALOG = "walkthrough_review";
+export { WALKTHROUGH_AUTHOR_SUBDIR, walkthroughRootDir } from '../core/walkthrough-root.js';
+/** One walkthrough pair of a run: the recorder unit and the author unit it records. */
+interface WalkthroughPair {
+    review: WorkUnit | null;
+    plan: WorkUnit | null;
+}
+/**
+ * The run's walkthrough pairs in plan order. A recorder pairs with the author its `depends_on` names,
+ * else the nearest author before it (the engine's `author_step_for`); an author with no recorder after
+ * it yet is a pair of its own (the walkthrough is still being written).
+ */
+export declare function walkthroughPairs(view: SessionView): WalkthroughPair[];
+/**
+ * The walkthrough half of `GET /runs/:id/acceptance` (WT-W2): one gate per `walkthrough_review` step
+ * the requirement names (`phases`, step ids), and the per-creator-step check states from the NEWEST
+ * walkthrough (only a sealed one proves anything).
+ */
+export declare function walkthroughAcceptance(adapter: Pick<CoreAdapter, 'workOutput'>, view: SessionView, phases: string[]): Promise<{
+    gates: WalkthroughGate[];
+    steps: WalkthroughStepState[];
+    newest: WalkthroughGate | null;
+}>;
+/** Everything studio renders for one walkthrough pair (the newest, or the one `step` names). */
+export declare function walkthroughView(view: SessionView, step?: string, adapter?: Pick<CoreAdapter, 'workOutput'>): Promise<WalkthroughView | null>;
+/** The biggest storyline the operator may PUT (the demo module shape is a few KB). */
+export declare const STORYLINE_MAX_BYTES: number;
+/** The storyline file the author writes, and crew's edit marker beside it (WT-W3). */
+export declare const STORYLINE_FILE = "storyline.mjs";
+export declare const STORYLINE_EDIT_FILE = "storyline.edit.json";
+/** What crew writes beside an operator-edited storyline: who edited it, when, and what. */
+export interface StorylineEditMarker {
+    edited_by: 'human';
+    actor: string;
+    at: string;
+    sha256: string;
+    /** The escalated unit the edit answers (its `ord`). */
+    ord: number;
+}
+/** A refusal whose message is safe to return (relative names only, never an absolute path). */
+export declare class StorylineWriteError extends Error {
+}
+/**
+ * WT-W3 (DES-walkthrough-proof §4.8 "Edit the check"): write the operator's storyline for the pair's
+ * author step — `<evidence_root>/author/<plan step>/storyline.mjs` plus `storyline.edit.json`
+ * (`edited_by: "human"`) — atomically (temp file + rename), refusing any path that does not resolve
+ * to a plain directory under the evidence root's `author/` (a planted link cannot redirect the write).
+ */
+export declare function writeStoryline(evidenceRoot: string, planStepId: string, text: string, marker: Omit<StorylineEditMarker, 'sha256' | 'edited_by'>): Promise<StorylineEditMarker>;
+export interface WalkthroughRouteDeps {
+    /** The run's open gate (the routes' shared resolution); `'no-log'` = this build cannot say. */
+    resolveOpenGate?: (runId: string) => Promise<{
+        ord: number;
+    } | null | 'no-log'>;
+    audit?: AuditLog;
+}
+export declare function registerWalkthroughRoutes(app: FastifyInstance, adapter: CoreAdapter, deps?: WalkthroughRouteDeps): void;
+//# sourceMappingURL=recording.d.ts.map

package/dist/api/recording.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recording.d.ts","sourceRoot":"","sources":["../../src/api/recording.ts"],"names":[],"mappings":"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"}