usesteady 0.1.0-alpha.1

package/dist/src/cursor/artifact-mapper.js

@@ -0,0 +1,203 @@
+/**
+ * Cursor artifact mapper — builds the initial CursorHandoffArtifact.
+ *
+ * ── Role ───────────────────────────────────────────────────────────────────────
+ *
+ *   Translates an IntakeResult (mode === "execute") into a CursorHandoffArtifact
+ *   with eligibility: "pending_confirmation" and an initial scopeConstraint.
+ *
+ *   This is the ONLY place that proposes allowedFiles. Specifically, it reads
+ *   parsedChange.filePath when present. When absent, allowedFiles starts empty.
+ *
+ * ── What this mapper does ──────────────────────────────────────────────────────
+ *
+ *   1. Extracts changeSpec from InterpretationResult (execute + structured) or
+ *      IntentInterpretation (execute + vague).
+ *   2. Sets initial allowedFiles = [parsedChange.filePath] or [].
+ *   3. Sets initial prohibitedPatterns from OCD policy (defensive defaults).
+ *   4. Sets eligibility = "pending_confirmation".
+ *   5. Sets ocdClearance = { status: "cleared", rulesFired: [], conflictsDetected: [] }
+ *      (OCD evaluator updates this separately — see ocd-evaluator.ts).
+ *
+ * ── What this mapper does NOT do ──────────────────────────────────────────────
+ *
+ *   - Does not read the filesystem (no path resolution)
+ *   - Does not call OCD (that is a separate step)
+ *   - Does not set eligibility to "approved_for_cursor" (only H does that)
+ *   - Does not validate H-provided paths (that is the delivery gate's job)
+ *   - Does not invent file paths from intent category
+ *
+ * ── CONSTRUCTION RULE: undefined-free payloads ────────────────────────────────
+ *
+ *   All payload objects must be undefined-free per UCP protocol invariant.
+ *   Optional fields are omitted entirely when absent. Never assigned undefined.
+ *
+ * See: docs/cursor-allowedfiles-policy.md — population source hierarchy
+ *      docs/cursor-integration-architecture.md — authority model
+ */
+import { hashObject } from "../ucp/hashes.js";
+// ─── Public API ───────────────────────────────────────────────────────────────
+/**
+ * Build the initial CursorHandoffArtifact from an IntakeResult.
+ *
+ * PRECONDITION: intake.mode === "execute". Callers must verify this before calling.
+ * Passing a non-execute IntakeResult is a caller contract violation.
+ *
+ * @param intake      The completed intake result (mode must be "execute").
+ * @param intentId    The ucp.intent.v1 envelope id — links back to the root intent.
+ * @param responseId  The ucp.response.v1 envelope id — links back to the mode decision.
+ * @param policy      The OCD policy config (for defensive prohibitedPatterns).
+ * @returns A CursorHandoffArtifact with eligibility: "pending_confirmation".
+ */
+export function buildCursorHandoffArtifact(intake, intentId, responseId, policy, parsedChange) {
+    const changeSpec = buildChangeSpec(intake, parsedChange);
+    const scopeConstraint = buildInitialScopeConstraint(changeSpec, policy);
+    const ocdClearance = buildInitialOCDClearance();
+    // id is content-addressed: same inputs → same id.
+    // ts is excluded (per UCP protocol). eligibility and approvedAt are NOT included
+    // in the id input — they are mutable fields that change as the flow progresses.
+    // The content identity is determined by what the edit IS, not its current state.
+    const idInput = {
+        intentId,
+        mode: "execute",
+        changeSpec,
+        responseId,
+        scopeConstraint,
+    };
+    const id = hashObject(idInput);
+    return {
+        id,
+        intentId,
+        responseId,
+        mode: "execute",
+        changeSpec,
+        ocdClearance,
+        eligibility: "pending_confirmation",
+        scopeConstraint,
+    };
+}
+/**
+ * Rebuild a CursorHandoffArtifact with a narrowed scopeConstraint.
+ *
+ * Called when H narrows the scope at ready_for_confirmation, or when a scope
+ * clarification answer updates allowedFiles. Produces a new artifact with a
+ * new content address (different scopeConstraint → different id).
+ *
+ * The new artifact retains the same intentId, responseId, and changeSpec.
+ * eligibility is reset to "pending_confirmation" — H must re-confirm.
+ *
+ * PRECONDITION: newAllowedFiles ⊆ current artifact.scopeConstraint.allowedFiles
+ *   OR current artifact.scopeConstraint.allowedFiles is empty (H setting from empty).
+ * Callers must enforce the non-widening rule before calling.
+ */
+export function narrowArtifactScope(artifact, newAllowedFiles, newAllowedScopes) {
+    const newScopeConstraint = {
+        allowedFiles: newAllowedFiles,
+        allowedScopes: newAllowedScopes ?? artifact.scopeConstraint.allowedScopes,
+        prohibitedPatterns: artifact.scopeConstraint.prohibitedPatterns,
+    };
+    const idInput = {
+        intentId: artifact.intentId,
+        mode: "execute",
+        changeSpec: artifact.changeSpec,
+        responseId: artifact.responseId,
+        scopeConstraint: newScopeConstraint,
+    };
+    const id = hashObject(idInput);
+    return {
+        id,
+        intentId: artifact.intentId,
+        responseId: artifact.responseId,
+        mode: "execute",
+        changeSpec: artifact.changeSpec,
+        ocdClearance: artifact.ocdClearance,
+        eligibility: "pending_confirmation",
+        scopeConstraint: newScopeConstraint,
+    };
+}
+/**
+ * Approve a CursorHandoffArtifact — set eligibility to "approved_for_cursor".
+ *
+ * This is the ONLY place that sets eligibility to "approved_for_cursor".
+ * Callers must verify that H has explicitly confirmed before calling.
+ *
+ * Returns a new artifact reference. The id does NOT change (eligibility and
+ * approvedAt are not part of the content-addressed id input).
+ */
+export function approveArtifact(artifact, confirmedAt) {
+    return {
+        ...artifact,
+        eligibility: "approved_for_cursor",
+        approvedAt: confirmedAt,
+    };
+}
+// ─── Internal builders ────────────────────────────────────────────────────────
+function buildChangeSpec(intake, parsedChange) {
+    const interp = intake.interpretation;
+    const intent = intake.guidance?.interpretation;
+    if (interp !== undefined) {
+        return buildChangeSpecFromInterpretation(interp, parsedChange);
+    }
+    if (intent !== undefined) {
+        return buildChangeSpecFromIntentInterpretation(intent);
+    }
+    // No interpretation of either kind — vague execute with no classification.
+    // certaintyLevel will be "unknown". changeSpec carries what we know.
+    return {
+        category: "unknown",
+        summary: intake.reason,
+        impact: [],
+        confidence: "low",
+        basis: [],
+    };
+}
+function buildChangeSpecFromInterpretation(interp, parsedChange) {
+    // InterpretationResult carries summary/impact/confidence/category.
+    // ParsedChange (oldValue, newValue, filePath) is threaded in separately by the
+    // coordinator, which has access to both simultaneously (e.g. from parseChange(input)).
+    return {
+        category: interp.category,
+        summary: interp.summary,
+        impact: interp.impact,
+        confidence: interp.confidence,
+        basis: [],
+        ...(parsedChange !== undefined ? { parsedChange } : {}),
+    };
+}
+function buildChangeSpecFromIntentInterpretation(intent) {
+    return {
+        category: intent.category,
+        summary: intent.summary,
+        impact: [],
+        confidence: intent.confidence,
+        basis: [...intent.basis],
+    };
+}
+function buildInitialScopeConstraint(changeSpec, policy) {
+    // PROPOSE: from parsedChange.filePath only.
+    const allowedFiles = changeSpec.parsedChange?.filePath != null
+        ? [changeSpec.parsedChange.filePath]
+        : [];
+    // CONSTRAIN: defensive prohibitions always applied.
+    const prohibitedPatterns = [
+        ...policy.alwaysProhibitedGlobs,
+        ...(allowedFiles.length === 0
+            ? policy.emptyAllowedFilesAdditionalProhibitions
+            : []),
+    ];
+    return {
+        allowedFiles,
+        allowedScopes: [],
+        prohibitedPatterns,
+    };
+}
+function buildInitialOCDClearance() {
+    // OCD clearance starts as "cleared" with no rules evaluated.
+    // The OCD evaluator (ocd-evaluator.ts) runs next and updates this.
+    return {
+        status: "cleared",
+        rulesFired: [],
+        conflictsDetected: [],
+    };
+}
+//# sourceMappingURL=artifact-mapper.js.map

package/dist/src/cursor/artifact-mapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-mapper.js","sourceRoot":"","sources":["../../../src/cursor/artifact-mapper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAOH,OAAO,EAAE,UAAU,EAAE,MAAqB,kBAAkB,CAAC;AAS7D,iFAAiF;AAEjF;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,0BAA0B,CACxC,MAA0B,EAC1B,QAAoB,EACpB,UAAoB,EACpB,MAA6B,EAC7B,YAA2B;IAE3B,MAAM,UAAU,GAAM,eAAe,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAC5D,MAAM,eAAe,GAAG,2BAA2B,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IACxE,MAAM,YAAY,GAAI,wBAAwB,EAAE,CAAC;IAEjD,kDAAkD;IAClD,iFAAiF;IACjF,gFAAgF;IAChF,iFAAiF;IACjF,MAAM,OAAO,GAAG;QACd,QAAQ;QACR,IAAI,EAAE,SAAkB;QACxB,UAAU;QACV,UAAU;QACV,eAAe;KAChB,CAAC;IACF,MAAM,EAAE,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC;IAE/B,OAAO;QACL,EAAE;QACF,QAAQ;QACR,UAAU;QACV,IAAI,EAAE,SAAS;QACf,UAAU;QACV,YAAY;QACZ,WAAW,EAAE,sBAAsB;QACnC,eAAe;KAChB,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,mBAAmB,CACjC,QAAsC,EACtC,eAAkC,EAClC,gBAAoC;IAEpC,MAAM,kBAAkB,GAA0B;QAChD,YAAY,EAAQ,eAAe;QACnC,aAAa,EAAO,gBAAgB,IAAI,QAAQ,CAAC,eAAe,CAAC,aAAa;QAC9E,kBAAkB,EAAE,QAAQ,CAAC,eAAe,CAAC,kBAAkB;KAChE,CAAC;IAEF,MAAM,OAAO,GAAG;QACd,QAAQ,EAAK,QAAQ,CAAC,QAAQ;QAC9B,IAAI,EAAS,SAAkB;QAC/B,UAAU,EAAG,QAAQ,CAAC,UAAU;QAChC,UAAU,EAAG,QAAQ,CAAC,UAAU;QAChC,eAAe,EAAE,kBAAkB;KACpC,CAAC;IACF,MAAM,EAAE,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC;IAE/B,OAAO;QACL,EAAE;QACF,QAAQ,EAAQ,QAAQ,CAAC,QAAQ;QACjC,UAAU,EAAM,QAAQ,CAAC,UAAU;QACnC,IAAI,EAAY,SAAS;QACzB,UAAU,EAAM,QAAQ,CAAC,UAAU;QACnC,YAAY,EAAI,QAAQ,CAAC,YAAY;QACrC,WAAW,EAAK,sBAAsB;QACtC,eAAe,EAAE,kBAAkB;KACpC,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAC7B,QAAkC,EAClC,WAAmB;IAEnB,OAAO;QACL,GAAG,QAAQ;QACX,WAAW,EAAE,qBAAqB;QAClC,UAAU,EAAG,WAAW;KACzB,CAAC;AACJ,CAAC;AAED,iFAAiF;AAEjF,SAAS,eAAe,CAAC,MAAoB,EAAE,YAA2B;IACxE,MAAM,MAAM,GAAG,MAAM,CAAC,cAAc,CAAC;IACrC,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,EAAE,cAAc,CAAC;IAE/C,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,OAAO,iCAAiC,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACjE,CAAC;IAED,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,OAAO,uCAAuC,CAAC,MAAM,CAAC,CAAC;IACzD,CAAC;IAED,2EAA2E;IAC3E,qEAAqE;IACrE,OAAO;QACL,QAAQ,EAAI,SAAS;QACrB,OAAO,EAAK,MAAM,CAAC,MAAM;QACzB,MAAM,EAAM,EAAE;QACd,UAAU,EAAE,KAAK;QACjB,KAAK,EAAO,EAAE;KACf,CAAC;AACJ,CAAC;AAED,SAAS,iCAAiC,CACxC,MAAkC,EAClC,YAA2B;IAE3B,mEAAmE;IACnE,+EAA+E;IAC/E,uFAAuF;IACvF,OAAO;QACL,QAAQ,EAAI,MAAM,CAAC,QAAQ;QAC3B,OAAO,EAAK,MAAM,CAAC,OAAO;QAC1B,MAAM,EAAM,MAAM,CAAC,MAAM;QACzB,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,KAAK,EAAO,EAAE;QACd,GAAG,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACxD,CAAC;AACJ,CAAC;AAED,SAAS,uCAAuC,CAC9C,MAA4B;IAE5B,OAAO;QACL,QAAQ,EAAI,MAAM,CAAC,QAAQ;QAC3B,OAAO,EAAK,MAAM,CAAC,OAAO;QAC1B,MAAM,EAAM,EAAE;QACd,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,KAAK,EAAO,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC;KAC9B,CAAC;AACJ,CAAC;AAED,SAAS,2BAA2B,CAClC,UAA4B,EAC5B,MAA2B;IAE3B,4CAA4C;IAC5C,MAAM,YAAY,GAChB,UAAU,CAAC,YAAY,EAAE,QAAQ,IAAI,IAAI;QACvC,CAAC,CAAC,CAAC,UAAU,CAAC,YAAY,CAAC,QAAQ,CAAC;QACpC,CAAC,CAAC,EAAE,CAAC;IAET,oDAAoD;IACpD,MAAM,kBAAkB,GAAsB;QAC5C,GAAG,MAAM,CAAC,qBAAqB;QAC/B,GAAG,CAAC,YAAY,CAAC,MAAM,KAAK,CAAC;YAC3B,CAAC,CAAC,MAAM,CAAC,uCAAuC;YAChD,CAAC,CAAC,EAAE,CAAC;KACR,CAAC;IAEF,OAAO;QACL,YAAY;QACZ,aAAa,EAAO,EAAE;QACtB,kBAAkB;KACnB,CAAC;AACJ,CAAC;AAED,SAAS,wBAAwB;IAC/B,6DAA6D;IAC7D,mEAAmE;IACnE,OAAO;QACL,MAAM,EAAc,SAAS;QAC7B,UAAU,EAAU,EAAE;QACtB,iBAAiB,EAAG,EAAE;KACvB,CAAC;AACJ,CAAC"}

package/dist/src/cursor/delivery-gate.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Cursor Delivery Gate — the boundary between UseSteady's authority system and Cursor.
+ *
+ * ── Role ───────────────────────────────────────────────────────────────────────
+ *
+ *   The delivery gate is the ONLY path through which a CursorHandoffArtifact
+ *   reaches Cursor. It enforces three invariants before any delivery occurs:
+ *
+ *     1. Eligibility check: artifact.eligibility === "approved_for_cursor"
+ *     2. Persistence: ucp.cursor_handoff.v1 persisted before Cursor is called
+ *     3. Immutability: artifact delivered === artifact persisted (same id)
+ *
+ *   After delivery, it persists either ucp.cursor_receipt.v1 (accepted) or
+ *   ucp.cursor_refused.v1 (refused) based on Cursor's response.
+ *
+ * ── Delivery mechanism ─────────────────────────────────────────────────────────
+ *
+ *   Currently: function call via injected CursorEditorPlugin.
+ *   This is the mechanism-agnostic contract: the same shapes apply regardless
+ *   of transport (function call, IPC, file drop, CLI pipe).
+ *
+ *   The plugin is injected at construction time so that:
+ *     - Tests can inject a stub plugin without coupling to Cursor internals
+ *     - The transport can be replaced without changing this module
+ *
+ * ── Three delivery paths ───────────────────────────────────────────────────────
+ *
+ *   Path A (happy):    persist handoff → call Cursor → accepted → persist receipt
+ *   Path B (scope):    persist handoff → call Cursor → refused_due_to_scope
+ *                        → persist refused → surface scope question
+ *   Path C (error):    persist handoff → call Cursor → refused_due_to_execution_error
+ *                        → persist refused → rejected
+ *
+ * ── Cursor plugin contract ─────────────────────────────────────────────────────
+ *
+ *   CursorEditorPlugin.receive() is the only call the gate makes into Cursor.
+ *   The plugin must:
+ *     - Accept only CursorDeliveryRequest
+ *     - Return only CursorResponse (one of three kinds)
+ *     - NOT reach back into the intake pipeline
+ *     - NOT call persistEnvelope (the gate owns all persistence)
+ *
+ * ── deliveryId semantics ───────────────────────────────────────────────────────
+ *
+ *   deliveryId is a delivery-attempt identifier, NOT a content identifier.
+ *   It is unique per attempt. Never use it for provenance chain links —
+ *   use artifact.id for those. See cursor-delivery-contract.md section 8.
+ *
+ * See: docs/cursor-delivery-contract.md — full delivery contract
+ *      docs/cursor-integration-architecture.md — boundary rules R1–R9
+ */
+import type { UCPEnvelope } from "../ucp/types.js";
+import type { CursorHandoffArtifact, CursorDeliveryRequest, CursorResponse, CursorRefusedDueToScope, CursorRefusedDueToExecutionError } from "./types.js";
+/**
+ * The interface the delivery gate uses to communicate with Cursor.
+ *
+ * This is the mechanism-agnostic seam. Implementations may use:
+ *   - Direct function calls (same process / module boundary)
+ *   - Local IPC (separate process)
+ *   - File drop (audit/debug path)
+ *
+ * The plugin is responsible for:
+ *   - Receiving the CursorDeliveryRequest
+ *   - Applying the edit within the artifact's scopeConstraint
+ *   - Returning exactly one CursorResponse kind
+ *   - Emitting ucp.execution_trace.v1 on completion (after accepted)
+ *
+ * The plugin must NOT:
+ *   - Re-derive intent from context
+ *   - Reach back to the intake pipeline
+ *   - Write files outside allowedFiles (when non-empty)
+ *   - Call persistEnvelope (the gate owns all persistence)
+ */
+export interface CursorEditorPlugin {
+    receive(request: CursorDeliveryRequest): Promise<CursorResponse>;
+}
+export type DeliveryGateResult = {
+    readonly outcome: "accepted";
+    readonly deliveryId: string;
+    readonly handoffEnvelopeId: string;
+    readonly receiptEnvelopeId: string;
+} | {
+    readonly outcome: "refused_due_to_scope";
+    readonly deliveryId: string;
+    readonly handoffEnvelopeId: string;
+    readonly refusedEnvelopeId: string;
+    readonly scopeQuestion: CursorRefusedDueToScope["scopeQuestion"];
+} | {
+    readonly outcome: "refused_due_to_execution_error";
+    readonly deliveryId: string;
+    readonly handoffEnvelopeId: string;
+    readonly refusedEnvelopeId: string;
+    readonly errorCode: CursorRefusedDueToExecutionError["errorCode"];
+    readonly detail: string;
+} | {
+    readonly outcome: "blocked_ineligible";
+    readonly reason: string;
+} | {
+    readonly outcome: "blocked_persistence_failure";
+    readonly reason: string;
+};
+export type CursorGateDeps = {
+    /**
+     * Persistence function for the critical handoff envelope.
+     * MUST throw on failure — a failure blocks delivery entirely.
+     * Default: persistEnvelopeOrThrow(storeDir, envelope)
+     */
+    persistStrict?: (envelope: UCPEnvelope<unknown>) => void;
+    /**
+     * Persistence function for non-critical envelopes (receipt, refused).
+     * Must NOT throw — errors are swallowed and logged.
+     * Default: persistEnvelope(storeDir, envelope)
+     */
+    persistBestEffort?: (envelope: UCPEnvelope<unknown>) => void;
+};
+export declare class CursorDeliveryGate {
+    private readonly plugin;
+    private readonly storeDir;
+    private readonly persistStrict;
+    private readonly persistBestEffort;
+    constructor(plugin: CursorEditorPlugin, storeDir: string, deps?: CursorGateDeps);
+    /**
+     * Deliver a CursorHandoffArtifact to Cursor.
+     *
+     * CONTRACT — callers must ensure:
+     *   - artifact.eligibility === "approved_for_cursor" (gate re-checks and blocks if not)
+     *   - artifact.ocdClearance.status is "cleared" or "conflict_accepted"
+     *   - artifact.approvedAt is set (H has confirmed)
+     *
+     * CONTRACT — this function guarantees:
+     *   - ucp.cursor_handoff.v1 is persisted BEFORE Cursor is called
+     *   - If persistence fails, Cursor is NOT called (blocked_persistence_failure)
+     *   - ucp.cursor_receipt.v1 is persisted when Cursor returns "accepted"
+     *   - ucp.cursor_refused.v1 is persisted when Cursor returns either refusal
+     *   - Receipt/refusal persistence failures are logged but do not block state transitions
+     *     (Cursor has already taken a position; the gate cannot undo that)
+     *
+     * @param artifact  The approved CursorHandoffArtifact to deliver.
+     * @returns         DeliveryGateResult describing the delivery outcome.
+     */
+    deliver(artifact: CursorHandoffArtifact): Promise<DeliveryGateResult>;
+    private tryPersistBestEffort;
+}
+//# sourceMappingURL=delivery-gate.d.ts.map

package/dist/src/cursor/delivery-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delivery-gate.d.ts","sourceRoot":"","sources":["../../../src/cursor/delivery-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAA2B,iBAAiB,CAAC;AAQxE,OAAO,KAAK,EACV,qBAAqB,EACrB,qBAAqB,EACrB,cAAc,EACd,uBAAuB,EACvB,gCAAgC,EACjC,MAAM,YAAY,CAAC;AAIpB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CAClE;AAID,MAAM,MAAM,kBAAkB,GAC1B;IACE,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACpC,GACD;IACE,QAAQ,CAAC,OAAO,EAAE,sBAAsB,CAAC;IACzC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,aAAa,EAAE,uBAAuB,CAAC,eAAe,CAAC,CAAC;CAClE,GACD;IACE,QAAQ,CAAC,OAAO,EAAE,gCAAgC,CAAC;IACnD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,SAAS,EAAE,gCAAgC,CAAC,WAAW,CAAC,CAAC;IAClE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,GACD;IACE,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,GACD;IACE,QAAQ,CAAC,OAAO,EAAE,6BAA6B,CAAC;IAChD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,CAAC;AAIN,MAAM,MAAM,cAAc,GAAG;IAC3B;;;;OAIG;IACH,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,WAAW,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;IAEzD;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,WAAW,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;CAC9D,CAAC;AAIF,qBAAa,kBAAkB;IAK3B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAL3B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA2C;IACzE,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA2C;gBAG1D,MAAM,EAAI,kBAAkB,EAC5B,QAAQ,EAAE,MAAM,EACjC,IAAI,GAAE,cAAmB;IAQ3B;;;;;;;;;;;;;;;;;;OAkBG;IACG,OAAO,CAAC,QAAQ,EAAE,qBAAqB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAiH3E,OAAO,CAAC,oBAAoB;CAS7B"}

package/dist/src/cursor/delivery-gate.js

@@ -0,0 +1,208 @@
+/**
+ * Cursor Delivery Gate — the boundary between UseSteady's authority system and Cursor.
+ *
+ * ── Role ───────────────────────────────────────────────────────────────────────
+ *
+ *   The delivery gate is the ONLY path through which a CursorHandoffArtifact
+ *   reaches Cursor. It enforces three invariants before any delivery occurs:
+ *
+ *     1. Eligibility check: artifact.eligibility === "approved_for_cursor"
+ *     2. Persistence: ucp.cursor_handoff.v1 persisted before Cursor is called
+ *     3. Immutability: artifact delivered === artifact persisted (same id)
+ *
+ *   After delivery, it persists either ucp.cursor_receipt.v1 (accepted) or
+ *   ucp.cursor_refused.v1 (refused) based on Cursor's response.
+ *
+ * ── Delivery mechanism ─────────────────────────────────────────────────────────
+ *
+ *   Currently: function call via injected CursorEditorPlugin.
+ *   This is the mechanism-agnostic contract: the same shapes apply regardless
+ *   of transport (function call, IPC, file drop, CLI pipe).
+ *
+ *   The plugin is injected at construction time so that:
+ *     - Tests can inject a stub plugin without coupling to Cursor internals
+ *     - The transport can be replaced without changing this module
+ *
+ * ── Three delivery paths ───────────────────────────────────────────────────────
+ *
+ *   Path A (happy):    persist handoff → call Cursor → accepted → persist receipt
+ *   Path B (scope):    persist handoff → call Cursor → refused_due_to_scope
+ *                        → persist refused → surface scope question
+ *   Path C (error):    persist handoff → call Cursor → refused_due_to_execution_error
+ *                        → persist refused → rejected
+ *
+ * ── Cursor plugin contract ─────────────────────────────────────────────────────
+ *
+ *   CursorEditorPlugin.receive() is the only call the gate makes into Cursor.
+ *   The plugin must:
+ *     - Accept only CursorDeliveryRequest
+ *     - Return only CursorResponse (one of three kinds)
+ *     - NOT reach back into the intake pipeline
+ *     - NOT call persistEnvelope (the gate owns all persistence)
+ *
+ * ── deliveryId semantics ───────────────────────────────────────────────────────
+ *
+ *   deliveryId is a delivery-attempt identifier, NOT a content identifier.
+ *   It is unique per attempt. Never use it for provenance chain links —
+ *   use artifact.id for those. See cursor-delivery-contract.md section 8.
+ *
+ * See: docs/cursor-delivery-contract.md — full delivery contract
+ *      docs/cursor-integration-architecture.md — boundary rules R1–R9
+ */
+import { hashObject } from "../ucp/hashes.js";
+import { persistEnvelope, persistEnvelopeOrThrow } from "../ucp/persistence/write.js";
+import { createCursorHandoffEnvelope, createCursorReceiptEnvelope, createCursorRefusedEnvelope, } from "../ucp/envelope.js";
+// ─── Delivery gate ────────────────────────────────────────────────────────────
+export class CursorDeliveryGate {
+    plugin;
+    storeDir;
+    persistStrict;
+    persistBestEffort;
+    constructor(plugin, storeDir, deps = {}) {
+        this.plugin = plugin;
+        this.storeDir = storeDir;
+        this.persistStrict = deps.persistStrict
+            ?? ((e) => persistEnvelopeOrThrow(storeDir, e));
+        this.persistBestEffort = deps.persistBestEffort
+            ?? ((e) => persistEnvelope(storeDir, e));
+    }
+    /**
+     * Deliver a CursorHandoffArtifact to Cursor.
+     *
+     * CONTRACT — callers must ensure:
+     *   - artifact.eligibility === "approved_for_cursor" (gate re-checks and blocks if not)
+     *   - artifact.ocdClearance.status is "cleared" or "conflict_accepted"
+     *   - artifact.approvedAt is set (H has confirmed)
+     *
+     * CONTRACT — this function guarantees:
+     *   - ucp.cursor_handoff.v1 is persisted BEFORE Cursor is called
+     *   - If persistence fails, Cursor is NOT called (blocked_persistence_failure)
+     *   - ucp.cursor_receipt.v1 is persisted when Cursor returns "accepted"
+     *   - ucp.cursor_refused.v1 is persisted when Cursor returns either refusal
+     *   - Receipt/refusal persistence failures are logged but do not block state transitions
+     *     (Cursor has already taken a position; the gate cannot undo that)
+     *
+     * @param artifact  The approved CursorHandoffArtifact to deliver.
+     * @returns         DeliveryGateResult describing the delivery outcome.
+     */
+    async deliver(artifact) {
+        // ── Eligibility check (R2 — Boundary Rule 2) ─────────────────────────────
+        if (artifact.eligibility !== "approved_for_cursor") {
+            return {
+                outcome: "blocked_ineligible",
+                reason: `Artifact eligibility is "${artifact.eligibility}", not "approved_for_cursor".`,
+            };
+        }
+        const sentAt = Date.now();
+        const deliveryId = computeDeliveryId(artifact.id, sentAt);
+        // ── Point 1: Persist handoff BEFORE calling Cursor ───────────────────────
+        const handoffEnvelope = createCursorHandoffEnvelope({
+            intentId: artifact.intentId,
+            responseId: artifact.responseId,
+            eligibility: "approved_for_cursor",
+            ocdStatus: artifact.ocdClearance.status,
+            rulesFired: [...artifact.ocdClearance.rulesFired],
+            changeCategory: artifact.changeSpec.category,
+            scopeAllowedFiles: [...artifact.scopeConstraint.allowedFiles],
+            confirmedByHuman: true,
+            confirmedAt: artifact.approvedAt ?? sentAt,
+        }, { parentId: artifact.responseId, rootId: artifact.intentId });
+        try {
+            this.persistStrict(handoffEnvelope);
+        }
+        catch (err) {
+            return {
+                outcome: "blocked_persistence_failure",
+                reason: `Failed to persist ucp.cursor_handoff.v1 before delivery: ${String(err)}`,
+            };
+        }
+        // ── Call Cursor ───────────────────────────────────────────────────────────
+        const request = { deliveryId, sentAt, artifact };
+        const response = await this.plugin.receive(request);
+        // ── Point 2a/2b: Persist based on Cursor's response ──────────────────────
+        if (response.kind === "accepted") {
+            const receiptEnvelope = createCursorReceiptEnvelope({
+                deliveryId: response.deliveryId,
+                handoffId: handoffEnvelope.id,
+                artifactId: response.artifactId,
+                receivedAt: response.receivedAt,
+            }, { parentId: handoffEnvelope.id, rootId: artifact.intentId });
+            this.tryPersistBestEffort(receiptEnvelope);
+            return {
+                outcome: "accepted",
+                deliveryId,
+                handoffEnvelopeId: handoffEnvelope.id,
+                receiptEnvelopeId: receiptEnvelope.id,
+            };
+        }
+        if (response.kind === "refused_due_to_scope") {
+            const refusedEnvelope = createCursorRefusedEnvelope(buildRefusedPayloadFromScope(response, handoffEnvelope.id, deliveryId), { parentId: handoffEnvelope.id, rootId: artifact.intentId });
+            this.tryPersistBestEffort(refusedEnvelope);
+            return {
+                outcome: "refused_due_to_scope",
+                deliveryId,
+                handoffEnvelopeId: handoffEnvelope.id,
+                refusedEnvelopeId: refusedEnvelope.id,
+                scopeQuestion: response.scopeQuestion,
+            };
+        }
+        // refused_due_to_execution_error (or unknown kind — treated as execution error)
+        const executionErrorResponse = response.kind === "refused_due_to_execution_error"
+            ? response
+            : null;
+        const refusedEnvelope = createCursorRefusedEnvelope({
+            deliveryId: deliveryId,
+            handoffId: handoffEnvelope.id,
+            artifactId: artifact.id,
+            receivedAt: Date.now(),
+            refusalKind: "refused_due_to_execution_error",
+            ...(executionErrorResponse !== null
+                ? { errorCode: executionErrorResponse.errorCode }
+                : { errorCode: "delivery_timeout" }),
+        }, { parentId: handoffEnvelope.id, rootId: artifact.intentId });
+        this.tryPersistBestEffort(refusedEnvelope);
+        return {
+            outcome: "refused_due_to_execution_error",
+            deliveryId,
+            handoffEnvelopeId: handoffEnvelope.id,
+            refusedEnvelopeId: refusedEnvelope.id,
+            errorCode: executionErrorResponse?.errorCode ?? "delivery_timeout",
+            detail: executionErrorResponse?.detail ?? "Cursor did not respond.",
+        };
+    }
+    // ── Internal ────────────────────────────────────────────────────────────────
+    tryPersistBestEffort(envelope) {
+        try {
+            this.persistBestEffort(envelope);
+        }
+        catch {
+            console.warn(`[cursor-delivery-gate] Non-critical persistence failed for envelope id=${envelope.id.slice(0, 8)}… type=${envelope.type}`);
+        }
+    }
+}
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+/**
+ * Compute a delivery-attempt identifier.
+ *
+ * IMPORTANT: deliveryId is an ATTEMPT identity, not a content identity.
+ * It is unique per delivery attempt, not per artifact.
+ * Use artifact.id for provenance chain links and content deduplication.
+ * Use deliveryId for transport-level correlation only.
+ */
+function computeDeliveryId(artifactId, sentAt) {
+    return hashObject({ artifactId, sentAt });
+}
+function buildRefusedPayloadFromScope(response, handoffId, deliveryId) {
+    const { scopeQuestion } = response;
+    return {
+        deliveryId,
+        handoffId,
+        artifactId: response.artifactId,
+        receivedAt: response.receivedAt,
+        refusalKind: "refused_due_to_scope",
+        scopeQuestionKind: scopeQuestion.questionKind,
+        scopeCandidates: [...scopeQuestion.candidates],
+        scopeSearchedFor: scopeQuestion.searchedFor,
+    };
+}
+//# sourceMappingURL=delivery-gate.js.map

package/dist/src/cursor/delivery-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delivery-gate.js","sourceRoot":"","sources":["../../../src/cursor/delivery-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAkC,kBAAkB,CAAC;AAC1E,OAAO,EAAE,eAAe,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACtF,OAAO,EACL,2BAA2B,EAC3B,2BAA2B,EAC3B,2BAA2B,GAC5B,MAAM,oBAAoB,CAAC;AAsF5B,iFAAiF;AAEjF,MAAM,OAAO,kBAAkB;IAKV;IACA;IALF,aAAa,CAA2C;IACxD,iBAAiB,CAA2C;IAE7E,YACmB,MAA4B,EAC5B,QAAgB,EACjC,OAAuB,EAAE;QAFR,WAAM,GAAN,MAAM,CAAsB;QAC5B,aAAQ,GAAR,QAAQ,CAAQ;QAGjC,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,aAAa;eAClC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,sBAAsB,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAC;QAClD,IAAI,CAAC,iBAAiB,GAAG,IAAI,CAAC,iBAAiB;eAC1C,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,eAAe,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAC;IAC7C,CAAC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,KAAK,CAAC,OAAO,CAAC,QAA+B;QAC3C,4EAA4E;QAC5E,IAAI,QAAQ,CAAC,WAAW,KAAK,qBAAqB,EAAE,CAAC;YACnD,OAAO;gBACL,OAAO,EAAE,oBAAoB;gBAC7B,MAAM,EAAG,4BAA4B,QAAQ,CAAC,WAAW,+BAA+B;aACzF,CAAC;QACJ,CAAC;QAED,MAAM,MAAM,GAAO,IAAI,CAAC,GAAG,EAAE,CAAC;QAC9B,MAAM,UAAU,GAAG,iBAAiB,CAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;QAE1D,4EAA4E;QAC5E,MAAM,eAAe,GAAG,2BAA2B,CACjD;YACE,QAAQ,EAAW,QAAQ,CAAC,QAAQ;YACpC,UAAU,EAAS,QAAQ,CAAC,UAAU;YACtC,WAAW,EAAQ,qBAAqB;YACxC,SAAS,EAAU,QAAQ,CAAC,YAAY,CAAC,MAAyC;YAClF,UAAU,EAAS,CAAC,GAAG,QAAQ,CAAC,YAAY,CAAC,UAAU,CAAC;YACxD,cAAc,EAAK,QAAQ,CAAC,UAAU,CAAC,QAAQ;YAC/C,iBAAiB,EAAE,CAAC,GAAG,QAAQ,CAAC,eAAe,CAAC,YAAY,CAAC;YAC7D,gBAAgB,EAAG,IAAI;YACvB,WAAW,EAAQ,QAAQ,CAAC,UAAU,IAAI,MAAM;SACjD,EACD,EAAE,QAAQ,EAAE,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,CAAC,QAAQ,EAAE,CAC7D,CAAC;QAEF,IAAI,CAAC;YACH,IAAI,CAAC,aAAa,CAAC,eAAe,CAAC,CAAC;QACtC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO;gBACL,OAAO,EAAE,6BAA6B;gBACtC,MAAM,EAAG,4DAA4D,MAAM,CAAC,GAAG,CAAC,EAAE;aACnF,CAAC;QACJ,CAAC;QAED,6EAA6E;QAC7E,MAAM,OAAO,GAA0B,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;QACxE,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAEpD,4EAA4E;QAC5E,IAAI,QAAQ,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YACjC,MAAM,eAAe,GAAG,2BAA2B,CACjD;gBACE,UAAU,EAAG,QAAQ,CAAC,UAAU;gBAChC,SAAS,EAAI,eAAe,CAAC,EAAE;gBAC/B,UAAU,EAAG,QAAQ,CAAC,UAAU;gBAChC,UAAU,EAAG,QAAQ,CAAC,UAAU;aACjC,EACD,EAAE,QAAQ,EAAE,eAAe,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,CAAC,QAAQ,EAAE,CAC5D,CAAC;YAEF,IAAI,CAAC,oBAAoB,CAAC,eAAe,CAAC,CAAC;YAE3C,OAAO;gBACL,OAAO,EAAa,UAAU;gBAC9B,UAAU;gBACV,iBAAiB,EAAG,eAAe,CAAC,EAAE;gBACtC,iBAAiB,EAAG,eAAe,CAAC,EAAE;aACvC,CAAC;QACJ,CAAC;QAED,IAAI,QAAQ,CAAC,IAAI,KAAK,sBAAsB,EAAE,CAAC;YAC7C,MAAM,eAAe,GAAG,2BAA2B,CACjD,4BAA4B,CAAC,QAAQ,EAAE,eAAe,CAAC,EAAE,EAAE,UAAU,CAAC,EACtE,EAAE,QAAQ,EAAE,eAAe,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,CAAC,QAAQ,EAAE,CAC5D,CAAC;YAEF,IAAI,CAAC,oBAAoB,CAAC,eAAe,CAAC,CAAC;YAE3C,OAAO;gBACL,OAAO,EAAa,sBAAsB;gBAC1C,UAAU;gBACV,iBAAiB,EAAG,eAAe,CAAC,EAAE;gBACtC,iBAAiB,EAAG,eAAe,CAAC,EAAE;gBACtC,aAAa,EAAO,QAAQ,CAAC,aAAa;aAC3C,CAAC;QACJ,CAAC;QAED,gFAAgF;QAChF,MAAM,sBAAsB,GAAG,QAAQ,CAAC,IAAI,KAAK,gCAAgC;YAC/E,CAAC,CAAC,QAAQ;YACV,CAAC,CAAC,IAAI,CAAC;QAET,MAAM,eAAe,GAAG,2BAA2B,CACjD;YACE,UAAU,EAAG,UAAU;YACvB,SAAS,EAAI,eAAe,CAAC,EAAE;YAC/B,UAAU,EAAG,QAAQ,CAAC,EAAE;YACxB,UAAU,EAAG,IAAI,CAAC,GAAG,EAAE;YACvB,WAAW,EAAE,gCAAgC;YAC7C,GAAG,CAAC,sBAAsB,KAAK,IAAI;gBACjC,CAAC,CAAC,EAAE,SAAS,EAAE,sBAAsB,CAAC,SAAS,EAAE;gBACjD,CAAC,CAAC,EAAE,SAAS,EAAE,kBAAkB,EAAE,CAAC;SACvC,EACD,EAAE,QAAQ,EAAE,eAAe,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,CAAC,QAAQ,EAAE,CAC5D,CAAC;QAEF,IAAI,CAAC,oBAAoB,CAAC,eAAe,CAAC,CAAC;QAE3C,OAAO;YACL,OAAO,EAAa,gCAAgC;YACpD,UAAU;YACV,iBAAiB,EAAG,eAAe,CAAC,EAAE;YACtC,iBAAiB,EAAG,eAAe,CAAC,EAAE;YACtC,SAAS,EAAW,sBAAsB,EAAE,SAAS,IAAI,kBAAkB;YAC3E,MAAM,EAAc,sBAAsB,EAAE,MAAM,IAAI,yBAAyB;SAChF,CAAC;IACJ,CAAC;IAED,+EAA+E;IAEvE,oBAAoB,CAAC,QAA8B;QACzD,IAAI,CAAC;YACH,IAAI,CAAC,iBAAiB,CAAC,QAAQ,CAAC,CAAC;QACnC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,CAAC,IAAI,CACV,0EAA0E,QAAQ,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,UAAU,QAAQ,CAAC,IAAI,EAAE,CAC3H,CAAC;QACJ,CAAC;IACH,CAAC;CACF;AAED,gFAAgF;AAEhF;;;;;;;GAOG;AACH,SAAS,iBAAiB,CAAC,UAAkB,EAAE,MAAc;IAC3D,OAAO,UAAU,CAAC,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC;AAC5C,CAAC;AAED,SAAS,4BAA4B,CACnC,QAAkC,EAClC,SAAiB,EACjB,UAAkB;IAElB,MAAM,EAAE,aAAa,EAAE,GAAG,QAAQ,CAAC;IACnC,OAAO;QACL,UAAU;QACV,SAAS;QACT,UAAU,EAAS,QAAQ,CAAC,UAAU;QACtC,UAAU,EAAS,QAAQ,CAAC,UAAU;QACtC,WAAW,EAAQ,sBAA+B;QAClD,iBAAiB,EAAE,aAAa,CAAC,YAAY;QAC7C,eAAe,EAAI,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC;QAChD,gBAAgB,EAAG,aAAa,CAAC,WAAW;KAC7C,CAAC;AACJ,CAAC"}

package/dist/src/cursor/glob-matcher.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Minimal glob matcher for OCD policy checks.
+ *
+ * Supports the glob features required for cursor integration:
+ *   double-star - matches any sequence including path separators
+ *   single-star - matches any sequence NOT including path separators
+ *   question    - matches exactly one non-separator character
+ *
+ * Matching rules:
+ *   Paths are normalized to forward slashes before matching.
+ *   Patterns are anchored (full match required, not substring).
+ *   Matching is case-insensitive.
+ *
+ * See: docs/cursor-allowedfiles-policy.md
+ */
+/**
+ * Return true if filePath matches the given glob pattern.
+ *
+ * @param filePath  File path to test. Backslashes are normalized to forward slashes.
+ * @param pattern   Glob pattern. Supports double-star, single-star, and question-mark.
+ */
+export declare function matchesGlob(filePath: string, pattern: string): boolean;
+/**
+ * Convert a glob pattern to an anchored, case-insensitive RegExp.
+ *
+ * Uses a character-by-character scan to avoid string placeholders that
+ * could introduce control characters or confuse source parsers.
+ */
+export declare function globToRegex(glob: string): RegExp;
+//# sourceMappingURL=glob-matcher.d.ts.map

package/dist/src/cursor/glob-matcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"glob-matcher.d.ts","sourceRoot":"","sources":["../../../src/cursor/glob-matcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAItE;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAkChD"}