wicked-crew 0.5.0 → 0.6.0

package/dist/interactive/edit-events.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Opt-in governed answering of wicked-interactive's STRUCTURAL edits (task #86, Phase 7c
+ * final leg — the draft leg's sibling, see draft-events.ts).
+ *
+ * wicked-interactive's service is model-free: a feedback batch's deterministic items
+ * (content/style/remove) are applied instantly by the service and NEVER reach this seam —
+ * only `structural-change` items climb. The service lands the deterministic partial as
+ * `_v{N}.html`, then emits `wicked.interactive.feedback.processed` with `awaiting_structural > 0`
+ * and the structural items INLINE (selector + instruction + the element's CURRENT fragment),
+ * expecting *something with intelligence* to answer with `wicked.interactive.edit.completed`
+ * carrying the edited fragments. Today that answerer is an ad-hoc `assist` agent session
+ * (assist skill Step 3); this module makes a crew-governed run the answerer instead.
+ *
+ * Same shape as the draft leg, with the structural deltas:
+ *
+ *  - VERSIONED TARGETING: the dedupe unit is the HANDOFF — `<doc>:v<version>` — not the doc
+ *    (one doc produces many structural handoffs over its life). The durable ledger keys on the
+ *    handoff, and the closing emit's idempotency key carries doc+version.
+ *  - INV-2 AT SCALE: unlike a first draft (no pre-existing anchors), an edited fragment MUST
+ *    retain every pre-existing `data-wid` BYTE-EXACT — the service silently rejects violations
+ *    (regenerate.js Inv2Error → the user's edit dies with no version landed). So this seam runs
+ *    a deterministic PRE-EMIT SELF-CHECK mirroring the assist skill's Step 2/Step 3c discipline:
+ *    parse the handed-off fragment's data-wids, verify the worker's fragment retains all of
+ *    them, and fail HONEST (error status, no emit) on any violation — a loud crew-side rejection
+ *    instead of a silent service-side one.
+ *  - HANDOFF BY FILE: fragments can be arbitrarily large and the PTY seat runner's prompt is
+ *    single-line, so the seam writes the items to a handoff JSON on disk and names its path in
+ *    the problem; the worker writes each edited fragment to a per-item output file (never JSON
+ *    with hand-escaped HTML — the exact failure the assist skill's Step 3c warns about).
+ *  - PROJECT ATTRIBUTION (the 7b surface): a project-bound doc's events carry `project_id`
+ *    (interactive's DES-PROJECT-001 enrichment); the governed run is launched with
+ *    `LaunchOptions.projectId` so the edit shows up in the project's activity feed.
+ */
+import { InteractiveHandoffLedger } from './ledger.js';
+import type { CoreAdapter } from '../core/adapter.js';
+import type { WorkflowDef } from '../core/types.js';
+export declare const FEEDBACK_PROCESSED = "wicked.interactive.feedback.processed";
+export declare const EDIT_COMPLETED = "wicked.interactive.edit.completed";
+/** Exact-type filter with a domain guard — no wildcard, one event type is the whole trigger. */
+export declare const INTERACTIVE_EDIT_BUS_FILTER = "wicked.interactive.feedback.processed@wicked-interactive";
+/** Dedicated durable-cursor identity — NOT the draft seam's, so the two interactive seams
+ *  advance independent cursors and stopping one never strands the other. */
+export declare const INTERACTIVE_EDIT_BUS_PLUGIN = "wicked-crew-interactive-edit";
+export declare const INTERACTIVE_EDIT_WORKFLOW = "interactive-edit";
+/**
+ * The governed workflow that fulfils a structural handoff. ONE agent phase — `edit` (build,
+ * creator role): the target fragments are already extracted and the instructions already
+ * written, so unlike the draft leg there is nothing left to plan; a recon phase would only
+ * burn a council turn re-reading a handoff the edit phase reads anyway.
+ *
+ * The phase `instructions` adapt the fragment-edit contract from interactive's assist skill
+ * (Step 2 + Step 3): rewrite each handed-off fragment per its instruction, preserve every
+ * pre-existing `data-wid` byte-for-byte, never mint new anchors, keep the markup well-formed,
+ * and never fabricate facts. SINGLE-LINE by contract (PTY seat runner, wicked-core FINDING-011).
+ *
+ * The gate is `auto` with `validator_pin: null` — no human gate, no deterministic floor —
+ * because this seam runs its own deterministic pre-emit self-check (INV-2) and interactive's
+ * apply path re-checks the same invariant; a wrong-but-anchor-safe edit is the user's to judge
+ * on the canvas, exactly as with the assist session it replaces.
+ */
+export declare const INTERACTIVE_EDIT_WORKFLOW_DEF: WorkflowDef;
+/** One structural item as handed off by the service (fragment = current outerHTML). */
+export interface StructuralItem {
+    selector: string;
+    instruction: string;
+    fragment: string;
+}
+/** The feedback-processed fields this seam acts on. */
+export interface StructuralHandoff {
+    documentId: string;
+    /** The partial version the service just landed — the PARENT of the version this edit makes. */
+    version: number;
+    items: StructuralItem[];
+    /** Present when the doc is project-bound (interactive's DES-PROJECT-001 enrichment). */
+    projectId?: string;
+}
+/**
+ * Parse a bus frame into a {@link StructuralHandoff}, or `null` when it is not an actionable
+ * structural handoff: wrong type, malformed payload, slug-invalid document_id, non-integer
+ * version, or NO usable structural items. Deterministic-only batches (`awaiting_structural: 0`)
+ * return `null` by construction — those edits already landed inside the service (edit-routing
+ * rung 1) and must never climb to a crew. Items whose `fragment` is missing/null (the service
+ * could not extract the element) are dropped: there is no current markup to edit.
+ */
+export declare function parseStructuralFeedback(eventType: string, payload: unknown): StructuralHandoff | null;
+/** The one dedupe unit of this seam: a handoff is doc+version, NOT doc-lifetime. */
+export declare function handoffKey(documentId: string, version: number): string;
+/** Deterministic bus idempotency key for the one edit this seam may land per handoff. */
+export declare function editIdempotencyKey(documentId: string, version: number): string;
+/** One row of the on-disk handoff file the worker reads. */
+export interface HandoffFileItem extends StructuralItem {
+    /** Absolute path the worker must write the edited fragment to. */
+    output_path: string;
+}
+/** Per-item output paths are INDEX-named (`fragment-1.html`, …), never selector-named — a
+ *  selector is bus-supplied data and must not name a filesystem path. */
+export declare function handoffFileItems(handoff: StructuralHandoff, outDir: string): HandoffFileItem[];
+/**
+ * The run's problem statement. Single-line (PTY contract); the bulky fragments ride in the
+ * handoff FILE, so only identity, the capped instruction gist, and the file path ride here.
+ */
+export declare function editProblem(handoff: StructuralHandoff, handoffPath: string): string;
+/** Every `data-wid` value in a fragment, in document order (duplicates preserved). */
+export declare function fragmentWids(fragment: string): string[];
+/** The data-wids of `before` missing from `after`, byte-exact. Non-empty = INV-2 violation.
+ *  Deliberately conservative: a wid that survives with different quoting/escaping counts as
+ *  dropped — the service compares exact attribute values, and fail-closed here beats a silent
+ *  Inv2Error rejection there. */
+export declare function droppedWids(before: string, after: string): string[];
+/** One rejected item of a self-check. */
+export interface EditViolation {
+    selector: string;
+    reason: string;
+}
+/** The self-check verdict over a whole handoff's worker output. */
+export interface EditCollection {
+    results: Array<{
+        selector: string;
+        fragment: string;
+    }>;
+    violations: EditViolation[];
+}
+/**
+ * Read the worker's per-item output files and verify each against the handed-off fragment:
+ * the file must exist non-empty, and every pre-existing `data-wid` must survive byte-exact.
+ * ANY violation fails the whole handoff (all-or-nothing): a partial apply would land a version
+ * the user believes complete, and the violating item would die silently service-side.
+ */
+export declare function collectEditResults(items: HandoffFileItem[]): EditCollection;
+/** Options for {@link startInteractiveEditSubscriber}. */
+export interface InteractiveEditOptions {
+    /** Bus SQLite db path. Omit to let wicked-bus resolve its own default
+     *  (honors `WICKED_BUS_DATA_DIR`) — where interactive's service emits unless redirected. */
+    dbPath?: string;
+    /** Poll cadence, ms (default 2000; tests shorten it). */
+    pollIntervalMs?: number;
+    /** Heartbeat narration cadence while a run is in flight, ms (default 15000 — inside the
+     *  UI's ~20s `status.requested` window so the canvas never reads frozen). */
+    heartbeatMs?: number;
+    /** Ledger file (default `~/.wicked-crew/interactive-edit-ledger.json`). */
+    ledgerPath?: string;
+    /** Where handoff files land and workers write edited fragments
+     *  (default `~/.wicked-crew/interactive-edits`). */
+    editDir?: string;
+    /** Seat roster JSON for the governed run (default: the production council roster).
+     *  The functional-test harness passes a deterministic stub seat here. */
+    clisJson?: string;
+    /** Called after a launch that FILED the run into a project (the handoff carried
+     *  `project_id`). The server wires this to the same post-commit half the launch route
+     *  performs: tag the run in the live membership index + emit `wicked.crew.membership.attached`
+     *  (the engine already attached the crew.run membership atomically with the launch). */
+    onRunFiled?: (runId: string, projectId: string) => void;
+    /** Diagnostics sink (default: console.error). */
+    log?: (message: string) => void;
+}
+/** Handle for a running subscription. */
+export interface InteractiveEditSubscription {
+    stop(): Promise<void> | void;
+    /** The durable ledger (diagnostics / tests). */
+    ledger: InteractiveHandoffLedger;
+}
+/**
+ * Arm the seam: register the `interactive-edit` workflow, open a durable
+ * `wicked.interactive.feedback.processed` subscription, and answer each handoff carrying
+ * structural items with a governed run that ends in `wicked.interactive.edit.completed`.
+ *
+ * Graceful degradation mirrors the draft seam: a missing wicked-bus package or an unopenable
+ * db LOGS and returns `null` — the daemon must still boot on a machine whose bus is broken;
+ * interactive's assist loop remains the (always-available) fallback answerer.
+ */
+export declare function startInteractiveEditSubscriber(adapter: CoreAdapter, opts?: InteractiveEditOptions): Promise<InteractiveEditSubscription | null>;
+//# sourceMappingURL=edit-events.d.ts.map

package/dist/interactive/edit-events.d.ts.map

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