@unbrained/pm-cli 2026.8.15 → 2026.8.17

package/dist/sdk/agent/refusal-reachability.js

@@ -1,12 +1,410 @@
-/** Recovery-reference kinds emitted by structured refusal envelopes. */
+/**
+ * @module sdk/agent/refusal-reachability
+ *
+ * Verifies real-entrypoint observations against refusal states declared by the
+ * generated public error-code catalog.
+ */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="631031be-883f-5a1d-bcb6-498208cf7922")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="70af2366-a675-5631-8edb-4ebeef4bb786")}catch(e){}}();
+import { stripTypeScriptTypes } from "node:module";
+/** Recovery-reference kinds emitted by structured refusal envelopes. */
 export const PM_RECOVERY_REFERENCE_KINDS = [
     "suggested_retry",
     "candidate_command",
     "example",
     "next_step",
+    "migration_hint",
+    "restore_with",
 ];
+const RECOVERY_REFERENCE_FIELD_CONTRACTS = {
+    suggested_retry: { kind: "suggested_retry", semantics: "recovery" },
+    retry_command: { kind: "suggested_retry", semantics: "recovery" },
+    candidate_command: { kind: "candidate_command", semantics: "recovery" },
+    candidate_commands: { kind: "candidate_command", semantics: "recovery" },
+    fallback_candidates: {
+        kind: "candidate_command",
+        semantics: "recovery",
+        nested_value_field: "command",
+    },
+    next_best_command: { kind: "candidate_command", semantics: "recovery" },
+    example: { kind: "example", semantics: "recovery" },
+    examples: { kind: "example", semantics: "recovery" },
+    next_step: { kind: "next_step", semantics: "recovery" },
+    next_steps: { kind: "next_step", semantics: "recovery" },
+    suggested_next_steps: { kind: "next_step", semantics: "recovery" },
+    migration_hint: { kind: "migration_hint", semantics: "replacement" },
+    migration_hints: { kind: "migration_hint", semantics: "replacement" },
+    restore_with: {
+        kind: "restore_with",
+        semantics: "behavior_preserving",
+    },
+};
+/** Literal envelope fields recognized as recovery-reference producers. */
+export const PM_RECOVERY_REFERENCE_FIELDS = Object.freeze(Object.keys(RECOVERY_REFERENCE_FIELD_CONTRACTS));
+/** Resolve an own recovery-field contract without trusting object prototypes. */
+function recoveryReferenceContract(field) {
+    if (!Object.hasOwn(RECOVERY_REFERENCE_FIELD_CONTRACTS, field))
+        return undefined;
+    return RECOVERY_REFERENCE_FIELD_CONTRACTS[field];
+}
+const SOURCE_REGEXP_PREFIX_PUNCTUATORS = new Set([
+    ..."=([{,:;!?&|+-*%^~<>",
+    "=>",
+]);
+function compareCodeUnits(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function skipQuotedSourceToken(source, index) {
+    const quote = source[index];
+    let next = index + 1;
+    let value = "";
+    while (next < source.length && source[next] !== quote) {
+        if (source[next] === "\\")
+            next += 2;
+        else {
+            value += source[next];
+            next += 1;
+        }
+    }
+    if (source[next] === quote)
+        next += 1;
+    return { next, value };
+}
+function canStartRegularExpression(previous) {
+    return (previous === undefined ||
+        (previous.kind === "punctuator" &&
+            SOURCE_REGEXP_PREFIX_PUNCTUATORS.has(previous.value)) ||
+        (previous.kind === "identifier" &&
+            ["return", "case", "throw", "else", "yield"].includes(previous.value)));
+}
+function sourceTriviaEnd(source, index) {
+    if (/\s/u.test(source[index]))
+        return index + 1;
+    if (source.startsWith("//", index)) {
+        const newline = source.indexOf("\n", index + 2);
+        return newline === -1 ? source.length : newline + 1;
+    }
+    if (!source.startsWith("/*", index))
+        return undefined;
+    // stripTypeScriptTypes validates block-comment termination before tokenization.
+    return source.indexOf("*/", index + 2) + 2;
+}
+function regularExpressionEnd(source, index, previous) {
+    if (source[index] !== "/" || !canStartRegularExpression(previous))
+        return undefined;
+    let next = index + 1;
+    let inClass = false;
+    while (next < source.length) {
+        if (source[next] === "\\")
+            next += 2;
+        else if (source[next] === "[") {
+            inClass = true;
+            next += 1;
+        }
+        else if (source[next] === "]") {
+            inClass = false;
+            next += 1;
+        }
+        else if (source[next] === "/" && !inClass) {
+            next += 1;
+            while (/[A-Za-z]/u.test(source.charAt(next)))
+                next += 1;
+            return next;
+        }
+        else
+            next += 1;
+    }
+    return next;
+}
+function readSourceSyntaxToken(source, index) {
+    const character = source[index];
+    if (character === "'" || character === '"' || character === "`") {
+        const quoted = skipQuotedSourceToken(source, index);
+        return character === "`"
+            ? { next: quoted.next }
+            : {
+                next: quoted.next,
+                token: { kind: "string", value: quoted.value, offset: index + 1 },
+            };
+    }
+    if (/[A-Za-z_$]/u.test(character)) {
+        let next = index + 1;
+        while (/[A-Za-z0-9_$]/u.test(source[next] ?? ""))
+            next += 1;
+        return {
+            next,
+            token: {
+                kind: "identifier",
+                value: source.slice(index, next),
+                offset: index,
+            },
+        };
+    }
+    const punctuator = source.startsWith("=>", index) ? "=>" : character;
+    return {
+        next: index + punctuator.length,
+        token: { kind: "punctuator", value: punctuator, offset: index },
+    };
+}
+/** Tokenize executable JavaScript while ignoring comments, templates, and regex bodies. */
+function tokenizeExecutableSource(source) {
+    const tokens = [];
+    let index = 0;
+    while (index < source.length) {
+        const ignoredEnd = sourceTriviaEnd(source, index);
+        if (ignoredEnd !== undefined) {
+            index = ignoredEnd;
+            continue;
+        }
+        const regexEnd = regularExpressionEnd(source, index, tokens.at(-1));
+        if (regexEnd !== undefined) {
+            index = regexEnd;
+            continue;
+        }
+        const read = readSourceSyntaxToken(source, index);
+        if (read.token)
+            tokens.push(read.token);
+        index = read.next;
+    }
+    return tokens;
+}
+const SOURCE_BRACE_FRAME_KINDS = new Set([
+    "object",
+    "block",
+    "pattern",
+]);
+const SOURCE_PATTERN_DECLARATIONS = new Set(["const", "let", "var"]);
+const SOURCE_CLOSING_TOKENS = new Set(["}", ")", "]"]);
+const SOURCE_OBJECT_PRECEDERS = new Set([
+    "=",
+    "(",
+    "[",
+    ",",
+    ":",
+    "?",
+    "return",
+]);
+function objectFrameKind(tokens, index, stack) {
+    const enclosingBrace = [...stack]
+        .reverse()
+        .find((frame) => SOURCE_BRACE_FRAME_KINDS.has(frame.kind));
+    if (enclosingBrace?.kind === "pattern")
+        return "pattern";
+    if (stack.at(-1)?.kind === "paren" && stack.at(-1)?.parameter_list)
+        return "pattern";
+    const previous = tokens[index - 1];
+    if (previous?.kind === "identifier" &&
+        SOURCE_PATTERN_DECLARATIONS.has(previous.value)) {
+        return "pattern";
+    }
+    if (previous?.value === "=>" || previous?.value === ")")
+        return "block";
+    return previous && SOURCE_OBJECT_PRECEDERS.has(previous.value)
+        ? "object"
+        : "block";
+}
+function openingSourceFrame(tokens, index, stack) {
+    const token = tokens[index];
+    if (token.value === "{") {
+        const kind = objectFrameKind(tokens, index, stack);
+        return {
+            kind,
+            ...(kind === "object" ? { member_start: true, candidates: [] } : {}),
+        };
+    }
+    if (token.value === "[")
+        return { kind: "array" };
+    if (token.value !== "(")
+        return undefined;
+    const previous = tokens[index - 1];
+    const beforePrevious = tokens[index - 2];
+    const parameterList = previous?.value === "function" || beforePrevious?.value === "function";
+    return { kind: "paren", ...(parameterList ? { parameter_list: true } : {}) };
+}
+function staticObjectMember(frame, token, next) {
+    if (frame?.kind !== "object" ||
+        !frame.member_start ||
+        (token.kind !== "identifier" && token.kind !== "string") ||
+        next?.value !== ":" ||
+        !/^[A-Za-z][A-Za-z0-9_]*$/u.test(token.value)) {
+        return undefined;
+    }
+    return { field: token.value, offset: token.offset };
+}
+function isPatternLikeObjectClosure(tokens, index) {
+    return ((tokens[index + 1]?.value === ")" && tokens[index + 2]?.value === "=>") ||
+        tokens[index + 1]?.value === "=");
+}
+/** Parse static object-literal members without treating patterns or labels as producers. */
+function scanSourcePropertyTokens(source) {
+    const tokens = tokenizeExecutableSource(stripTypeScriptTypes(source, { mode: "strip" }));
+    const properties = [];
+    const stack = [];
+    for (const [index, token] of tokens.entries()) {
+        const frame = stack.at(-1);
+        const property = staticObjectMember(frame, token, tokens[index + 1]);
+        if (property)
+            frame.candidates.push(property);
+        const opening = openingSourceFrame(tokens, index, stack);
+        if (opening) {
+            stack.push(opening);
+        }
+        else if (SOURCE_CLOSING_TOKENS.has(token.value)) {
+            const closed = stack.pop();
+            if (closed?.kind === "object" &&
+                !isPatternLikeObjectClosure(tokens, index)) {
+                properties.push(...closed.candidates);
+            }
+        }
+        else if (token.value === "," && frame?.kind === "object") {
+            frame.member_start = true;
+        }
+        else if (frame?.kind === "object" && token.value !== ":") {
+            frame.member_start = false;
+        }
+    }
+    return properties;
+}
+function sourceLineStarts(source) {
+    const starts = [0];
+    for (let index = 0; index < source.length; index += 1) {
+        if (source[index] === "\n")
+            starts.push(index + 1);
+    }
+    return starts;
+}
+function sourceLineAtOffset(starts, offset) {
+    let low = 0;
+    let high = starts.length;
+    while (low < high) {
+        const middle = Math.floor((low + high) / 2);
+        if (starts[middle] <= offset)
+            low = middle + 1;
+        else
+            high = middle;
+    }
+    return low;
+}
+/** Census syntax-parsed structured-envelope producers without executing source code. */
+export function censusPmRecoveryReferenceProducers(sources) {
+    const producers = [];
+    const findings = [];
+    for (const source of [...sources].sort((left, right) => compareCodeUnits(left.path, right.path))) {
+        const lineStarts = sourceLineStarts(source.content);
+        let properties;
+        try {
+            properties = scanSourcePropertyTokens(source.content);
+        }
+        catch (error) {
+            findings.push({
+                kind: "invalid_source",
+                subject: source.path,
+                detail: `${source.path} could not be parsed for recovery producers: ${String(error)}.`,
+            });
+            continue;
+        }
+        for (const property of properties) {
+            const field = property.field;
+            const line = sourceLineAtOffset(lineStarts, property.offset);
+            const contract = recoveryReferenceContract(field);
+            if (contract) {
+                producers.push({
+                    path: source.path,
+                    line,
+                    field: field,
+                    kind: contract.kind,
+                });
+            }
+            else if (/(?:retry_command|candidate_command|fallback_candidate|next_best_command|example|next_step|migration_hint|restore_with)/u.test(field) &&
+                !/(?:_total|_truncated)$/u.test(field)) {
+                findings.push({
+                    kind: "unknown_recovery_field",
+                    subject: `${source.path}:${line}:${field}`,
+                    detail: `${field} resembles a recovery reference but has no typed field contract.`,
+                });
+            }
+        }
+    }
+    const producerCountByKind = Object.fromEntries(PM_RECOVERY_REFERENCE_KINDS.map((kind) => [
+        kind,
+        producers.filter((producer) => producer.kind === kind).length,
+    ]));
+    for (const kind of PM_RECOVERY_REFERENCE_KINDS) {
+        if (producerCountByKind[kind] === 0) {
+            findings.push({
+                kind: "missing_kind_producer",
+                subject: kind,
+                detail: `No source producer emits the ${kind} recovery-reference kind.`,
+            });
+        }
+    }
+    producers.sort((left, right) => left.path !== right.path
+        ? compareCodeUnits(left.path, right.path)
+        : left.line !== right.line
+            ? left.line - right.line
+            : compareCodeUnits(left.field, right.field));
+    findings.sort((left, right) => left.subject !== right.subject
+        ? compareCodeUnits(left.subject, right.subject)
+        : compareCodeUnits(left.kind, right.kind));
+    return {
+        ok: findings.length === 0,
+        scanned_file_count: sources.length,
+        producer_count: producers.length,
+        producer_count_by_kind: producerCountByKind,
+        producers,
+        findings,
+    };
+}
+/** Derive typed obligations from every recognized recovery field in an emitted envelope. */
+export function derivePmRecoveryReferenceObligations(probeId, envelope) {
+    const obligations = [];
+    const visit = (value, path) => {
+        if (Array.isArray(value)) {
+            value.forEach((entry, index) => visit(entry, [...path, String(index)]));
+            return;
+        }
+        if (typeof value !== "object" || value === null)
+            return;
+        for (const [key, entry] of Object.entries(value).sort(([left], [right]) => compareCodeUnits(left, right))) {
+            const baseContract = recoveryReferenceContract(key);
+            const contract = baseContract?.kind === "migration_hint" &&
+                value.semantics === "behavior_preserving"
+                ? { ...baseContract, semantics: "behavior_preserving" }
+                : baseContract;
+            const entries = [entry].flat();
+            if (contract !== undefined) {
+                entries.forEach((candidate, index) => {
+                    const nestedValueField = "nested_value_field" in contract &&
+                        typeof contract.nested_value_field === "string"
+                        ? contract.nested_value_field
+                        : undefined;
+                    const resolvedCandidate = nestedValueField &&
+                        typeof candidate === "object" &&
+                        candidate !== null &&
+                        !Array.isArray(candidate)
+                        ? candidate[nestedValueField]
+                        : candidate;
+                    if (typeof resolvedCandidate !== "string" ||
+                        resolvedCandidate.trim().length === 0)
+                        return;
+                    const coordinate = [...path, key, String(index)]
+                        .map((segment) => encodeURIComponent(segment))
+                        .join("/");
+                    obligations.push({
+                        id: `${probeId}:${contract.kind}:${coordinate}`,
+                        probe_id: probeId,
+                        kind: contract.kind,
+                        semantics: contract.semantics,
+                        value: resolvedCandidate,
+                    });
+                });
+            }
+            visit(entry, [...path, key]);
+        }
+    };
+    visit(envelope, []);
+    return obligations;
+}
 /** Compare declared refusal states with real-entrypoint observations. */
 export function verifyPmRefusalReachability(catalog, observations) {
     const declarations = catalog.flatMap((contract) => (contract.owned_states ?? []).map((state) => ({ contract, state })));
@@ -129,6 +527,13 @@ export function verifyPmRecoveryReferences(obligations, observations) {
                 detail: `Recovery reference ${obligation.value} did not reach its promised target.`,
             });
         }
+        else if (observation.semantics !== obligation.semantics) {
+            findings.push({
+                kind: "wrong_semantics",
+                reference_id: obligation.id,
+                detail: `Recovery reference ${obligation.value} promised ${obligation.semantics}; proof demonstrated ${observation.semantics}.`,
+            });
+        }
     }
     const coverageByKind = PM_RECOVERY_REFERENCE_KINDS.map((kind) => {
         const kindObligations = obligations.filter((obligation) => obligation.kind === kind);
@@ -140,7 +545,12 @@ export function verifyPmRecoveryReferences(obligations, observations) {
             kind,
             declared: kindObligations.length,
             observed: kindObservations.length,
-            passed: kindObservations.filter(({ reachable }) => reachable).length,
+            passed: kindObligations.filter((obligation) => {
+                const observation = observationsById.get(obligation.id);
+                return (!duplicateIds.has(obligation.id) &&
+                    observation?.reachable === true &&
+                    observation.semantics === obligation.semantics);
+            }).length,
         };
     });
     findings.sort((left, right) => left.reference_id !== right.reference_id
@@ -157,4 +567,4 @@ export function verifyPmRecoveryReferences(obligations, observations) {
     };
 }
 //# sourceMappingURL=refusal-reachability.js.map
-//# debugId=631031be-883f-5a1d-bcb6-498208cf7922
+//# debugId=70af2366-a675-5631-8edb-4ebeef4bb786

package/dist/sdk/author-attribution.d.ts

@@ -46,12 +46,63 @@ export interface AcknowledgeUnknownAuthorEventsOptions {
     /** Select every currently actionable, undispositioned event in the tracker. */
     all_actionable?: boolean;
     /** Principal attributed by maintainer review. */
-    attributed_author: string;
+    attributed_author?: string;
     /** Reviewer appending the disposition event. */
-    reviewer: string;
+    reviewer?: string;
     /** Evidence-backed rationale for the attribution. */
-    reason: string;
+    reason?: string;
+    /** Resolve and return the selected plan without appending history. */
+    dry_run?: boolean;
+    /** Fingerprint from the exact preview plan being applied. */
+    plan_fingerprint?: string;
+    /** Maximum coordinate rows included in the returned plan. */
+    coordinate_limit?: number;
 }
+/** One source-bound coordinate in an author-acknowledgement plan. */
+export interface UnknownAuthorAcknowledgmentPlanCoordinate extends UnknownAuthorHistoryEvent {
+    /** SHA-256 of the exact immutable JSONL source line. */
+    source_event_hash: string;
+    /** Whether the row is undispositioned or an explicit apply would supersede it. */
+    disposition: "actionable" | "already_acknowledged";
+}
+/** Deterministic preview shared by CLI, SDK, and MCP apply paths. */
+export interface UnknownAuthorAcknowledgmentPlan {
+    /** Selector family resolved by the plan. */
+    selection: {
+        kind: "events" | "all_actionable";
+    };
+    /** Complete number of unique selected coordinates. */
+    selected_count: number;
+    /** Selected coordinates not covered by an earlier disposition. */
+    actionable_count: number;
+    /** Coordinates an explicit-events apply would supersede. */
+    already_acknowledged_count: number;
+    /** Coordinate rows omitted only from this bounded preview. */
+    omitted_count: number;
+    /** Stable ordered prefix of the complete selected set. */
+    coordinates: UnknownAuthorAcknowledgmentPlanCoordinate[];
+    /** SHA-256 over selection kind and every complete source-bound coordinate. */
+    plan_fingerprint: string;
+}
+/** Structured preview or apply result for immutable author acknowledgement. */
+export interface UnknownAuthorAcknowledgmentResult {
+    /** Whether this invocation was a read-only preview. */
+    dry_run: boolean;
+    /** Whether an append-only workspace event was written. */
+    mutated: boolean;
+    /** Number of coordinates written to the appended disposition. */
+    acknowledged: number;
+    /** Effect-aware command outcome. */
+    outcome: "preview" | "effect" | "no_effect" | "partial_effect";
+    /** Stable shell and transport exit paired with the outcome. */
+    exit_code: 0 | 6 | 7;
+    /** Exact plan used for preview or apply. */
+    plan: UnknownAuthorAcknowledgmentPlan;
+    /** Appended workspace history path when mutation occurred. */
+    history_path?: string;
+}
+/** Resolve a deterministic, source-bound author-acknowledgement preview. */
+export declare function planUnknownAuthorHistoryAcknowledgment(pmRoot: string, selector: Pick<AcknowledgeUnknownAuthorEventsOptions, "events" | "all_actionable">, coordinateLimit?: number): Promise<UnknownAuthorAcknowledgmentPlan>;
 /** Resolve the mutually exclusive CLI and SDK acknowledgment selectors. */
 export declare function resolveUnknownAuthorAcknowledgmentSelector(rawEvents: readonly string[], allActionable: boolean): {
     events: UnknownAuthorHistoryEvent[];
@@ -60,15 +111,9 @@ export declare function resolveUnknownAuthorAcknowledgmentSelector(rawEvents: re
 /** Parse user-facing item or workspace history coordinates into SDK events. */
 export declare function parseUnknownAuthorHistoryEventCoordinates(values: readonly string[]): UnknownAuthorHistoryEvent[];
 /** Normalize an untyped transport payload and execute author acknowledgment. */
-export declare function acknowledgeUnknownAuthorHistoryEventsFromTransport(pmRoot: string, input: Record<string, unknown>): Promise<{
-    acknowledged: number;
-    history_path: string;
-}>;
+export declare function acknowledgeUnknownAuthorHistoryEventsFromTransport(pmRoot: string, input: Record<string, unknown>): Promise<UnknownAuthorAcknowledgmentResult>;
 /**
  * Append an audited disposition for immutable unknown-author events without
  * rewriting their original streams.
  */
-export declare function acknowledgeUnknownAuthorHistoryEvents(pmRoot: string, options: AcknowledgeUnknownAuthorEventsOptions): Promise<{
-    acknowledged: number;
-    history_path: string;
-}>;
+export declare function acknowledgeUnknownAuthorHistoryEvents(pmRoot: string, options: AcknowledgeUnknownAuthorEventsOptions): Promise<UnknownAuthorAcknowledgmentResult>;