productfoo 0.0.0-stage → 1.0.1

package/dist-public/src/bugCapsule.js

@@ -0,0 +1,227 @@
+import { createHash, randomBytes } from "node:crypto";
+const MAX_STRING_LENGTH = 4_096;
+const MAX_ARRAY_LENGTH = 100;
+const UUID_V7 = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const RFC_3339_UTC = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d+)?Z$/;
+const SHA_256_DIGEST = /^sha256:[0-9a-f]{64}$/;
+const ERROR_CLASSES = new Set(["none", "usage_error", "gate_block", "not_found", "io_error", "command_error"]);
+const ERROR_CODES = new Set([
+    "E_COMMAND_MISSING", "E_PACKET_DIR_MISSING", "E_SWARM_TARGET_MISSING", "E_IDEATE_IDEA_MISSING", "E_SPEC_WORK_MISSING", "E_UNKNOWN_DOMAIN", "E_BAD_FLAG", "E_NOT_A_RESEARCH_PAPER",
+    "E_PACKET_NOT_FOUND", "E_SPEC_NOT_FOUND", "E_SKILL_NOT_FOUND",
+    "E_GATE_B1_SECRET", "E_GATE_B2_SPEC_ID", "E_GATE_B4_BUDGET", "E_GATE_B5_UNGOVERNED", "E_GATE_B5_CLAIM_UNLABELED", "E_GATE_BLOCKED", "E_GATE_INTERVIEW", "E_CONTRACT_DRIFT",
+    "E_IO", "E_UNKNOWN",
+]);
+function jcs(value) {
+    if (value === null || typeof value === "boolean" || typeof value === "string")
+        return JSON.stringify(value);
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new Error("canonical JSON refuses non-finite numbers");
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value))
+        return `[${value.map(jcs).join(",")}]`;
+    if (typeof value === "object") {
+        const source = value;
+        return `{${Object.keys(source).sort().map((key) => `${JSON.stringify(key)}:${jcs(source[key])}`).join(",")}}`;
+    }
+    throw new Error(`canonical JSON refuses ${typeof value}`);
+}
+export function canonicalBytes(capsule) {
+    return Buffer.from(jcs(capsule), "utf8");
+}
+export function payloadDigest(capsule) {
+    return `sha256:${createHash("sha256").update(canonicalBytes(capsule)).digest("hex")}`;
+}
+export function uuidV7(nowMs = Date.now(), entropy = randomBytes(10)) {
+    if (!Number.isSafeInteger(nowMs) || nowMs < 0 || nowMs > 0xffff_ffff_ffff)
+        throw new Error("UUIDv7 timestamp must fit in 48 bits");
+    if (entropy.length !== 10)
+        throw new Error("UUIDv7 entropy must be 10 bytes");
+    const bytes = Buffer.alloc(16);
+    let timestamp = BigInt(nowMs);
+    for (let index = 5; index >= 0; index -= 1) {
+        bytes[index] = Number(timestamp & 0xffn);
+        timestamp >>= 8n;
+    }
+    entropy.copy(bytes, 6);
+    bytes[6] = 0x70 | (bytes[6] & 0x0f);
+    bytes[8] = 0x80 | (bytes[8] & 0x3f);
+    const hex = bytes.toString("hex");
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+function object(value, label) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        throw new Error(`${label} must be an object`);
+    return value;
+}
+function closedObject(value, label, allowed, required = allowed) {
+    const source = object(value, label);
+    for (const key of Object.keys(source)) {
+        if (!allowed.includes(key))
+            throw new Error(`unknown ${label} field: ${key}`);
+    }
+    for (const key of required) {
+        if (!(key in source))
+            throw new Error(`${label} field is required: ${key}`);
+    }
+    return source;
+}
+function boundedString(value, label) {
+    if (typeof value !== "string")
+        throw new Error(`${label} must be a string`);
+    if (value.length > MAX_STRING_LENGTH)
+        throw new Error(`${label} must be at most ${MAX_STRING_LENGTH} characters`);
+    return value;
+}
+function boundedArray(value, label) {
+    if (!Array.isArray(value))
+        throw new Error(`${label} must be an array`);
+    if (value.length > MAX_ARRAY_LENGTH)
+        throw new Error(`${label} must contain at most ${MAX_ARRAY_LENGTH} entries`);
+    return value;
+}
+function uuid(value, label) {
+    const parsed = boundedString(value, label);
+    if (!UUID_V7.test(parsed))
+        throw new Error(`${label} must be a UUIDv7`);
+    return parsed;
+}
+function rfc3339(value, label) {
+    const parsed = boundedString(value, label);
+    const match = RFC_3339_UTC.exec(parsed);
+    const date = new Date(parsed);
+    if (match === null ||
+        Number.isNaN(date.valueOf()) ||
+        date.getUTCFullYear() !== Number(match[1]) ||
+        date.getUTCMonth() + 1 !== Number(match[2]) ||
+        date.getUTCDate() !== Number(match[3]) ||
+        date.getUTCHours() !== Number(match[4]) ||
+        date.getUTCMinutes() !== Number(match[5]) ||
+        date.getUTCSeconds() !== Number(match[6])) {
+        throw new Error(`${label} must be RFC 3339 UTC`);
+    }
+    return parsed;
+}
+function fieldValue(value, label) {
+    const source = object(value, label);
+    const state = source.state;
+    if (state === "collected") {
+        if (!("value" in source))
+            throw new Error("collected field requires value");
+        const collected = closedObject(source, label, ["state", "value"]);
+        return { state, value: boundedString(collected.value, `${label}.value`) };
+    }
+    if (state === "not_collected" || state === "withheld" || state === "unavailable") {
+        if ("value" in source)
+            throw new Error("non-collected field cannot contain value");
+        const absent = closedObject(source, label, ["state", "reason"]);
+        return { state, reason: boundedString(absent.reason, `${label}.reason`) };
+    }
+    throw new Error(`${label}.state is invalid`);
+}
+function requiredStringFields(value, label, fields) {
+    const source = closedObject(value, label, fields);
+    for (const field of fields)
+        boundedString(source[field], `${label}.${field}`);
+}
+export function parseBugCapsule(value) {
+    const capsule = closedObject(value, "BugCapsule", [
+        "schema_version", "capsule_id", "occurred_at", "producer", "product", "invocation", "failure", "report", "evidence", "similarity", "links", "extensions",
+    ]);
+    if (capsule.schema_version !== "0.1")
+        throw new Error("BugCapsule.schema_version must be 0.1");
+    uuid(capsule.capsule_id, "BugCapsule.capsule_id");
+    rfc3339(capsule.occurred_at, "BugCapsule.occurred_at");
+    requiredStringFields(capsule.producer, "BugCapsule.producer", ["name", "version"]);
+    requiredStringFields(capsule.product, "BugCapsule.product", ["name", "component", "version"]);
+    const invocation = closedObject(capsule.invocation, "BugCapsule.invocation", ["command", "runtime"]);
+    boundedString(invocation.command, "BugCapsule.invocation.command");
+    requiredStringFields(invocation.runtime, "BugCapsule.invocation.runtime", ["node", "platform", "arch"]);
+    const failure = closedObject(capsule.failure, "BugCapsule.failure", ["class", "code", "classifier_version", "classification", "message", "stack"]);
+    if (!ERROR_CLASSES.has(failure.class))
+        throw new Error("BugCapsule.failure.class is invalid");
+    if (!ERROR_CODES.has(failure.code))
+        throw new Error("BugCapsule.failure.code is invalid");
+    if (failure.classifier_version !== "0.1")
+        throw new Error("BugCapsule.failure.classifier_version must be 0.1");
+    if (failure.classification !== "known" && failure.classification !== "fallback")
+        throw new Error("BugCapsule.failure.classification is invalid");
+    fieldValue(failure.message, "BugCapsule.failure.message");
+    fieldValue(failure.stack, "BugCapsule.failure.stack");
+    const report = closedObject(capsule.report, "BugCapsule.report", ["expected", "actual", "reproduction"]);
+    fieldValue(report.expected, "BugCapsule.report.expected");
+    fieldValue(report.actual, "BugCapsule.report.actual");
+    fieldValue(report.reproduction, "BugCapsule.report.reproduction");
+    for (const [index, entry] of boundedArray(capsule.evidence, "BugCapsule.evidence").entries()) {
+        const evidence = closedObject(entry, `BugCapsule.evidence[${index}]`, ["kind", "state", "content_type"]);
+        if (evidence.kind !== "diagnostic" && evidence.kind !== "user_report")
+            throw new Error(`BugCapsule.evidence[${index}].kind is invalid`);
+        if (!["collected", "not_collected", "withheld", "unavailable"].includes(String(evidence.state)))
+            throw new Error(`BugCapsule.evidence[${index}].state is invalid`);
+        boundedString(evidence.content_type, `BugCapsule.evidence[${index}].content_type`);
+    }
+    const similarity = closedObject(capsule.similarity, "BugCapsule.similarity", ["version", "signals"]);
+    if (similarity.version !== "0.1")
+        throw new Error("BugCapsule.similarity.version must be 0.1");
+    for (const [index, signal] of boundedArray(similarity.signals, "BugCapsule.similarity.signals").entries()) {
+        const parsed = closedObject(signal, `BugCapsule.similarity.signals[${index}]`, ["kind", "value"]);
+        if (parsed.kind !== "error_fingerprint")
+            throw new Error(`BugCapsule.similarity.signals[${index}].kind is invalid`);
+        boundedString(parsed.value, `BugCapsule.similarity.signals[${index}].value`);
+    }
+    for (const [index, link] of boundedArray(capsule.links, "BugCapsule.links").entries()) {
+        const parsed = closedObject(link, `BugCapsule.links[${index}]`, ["relation", "provider", "external_id", "provenance", "authority"]);
+        boundedString(parsed.relation, `BugCapsule.links[${index}].relation`);
+        boundedString(parsed.provider, `BugCapsule.links[${index}].provider`);
+        boundedString(parsed.external_id, `BugCapsule.links[${index}].external_id`);
+        if (parsed.provenance !== "reporter_observed")
+            throw new Error(`BugCapsule.links[${index}].provenance is invalid`);
+        if (parsed.authority !== "reference")
+            throw new Error(`BugCapsule.links[${index}].authority is invalid`);
+    }
+    const extensions = object(capsule.extensions, "BugCapsule.extensions");
+    if (extensions.foo !== undefined) {
+        const foo = closedObject(extensions.foo, "BugCapsule.extensions.foo", ["spec_context"], []);
+        if (foo.spec_context !== undefined) {
+            const context = closedObject(foo.spec_context, "BugCapsule.extensions.foo.spec_context", ["spec_id", "packet_path", "revision", "requirement_ids", "task_ids", "provenance"], ["spec_id", "packet_path", "requirement_ids", "task_ids", "provenance"]);
+            boundedString(context.spec_id, "BugCapsule.extensions.foo.spec_context.spec_id");
+            boundedString(context.packet_path, "BugCapsule.extensions.foo.spec_context.packet_path");
+            if (context.revision !== undefined)
+                boundedString(context.revision, "BugCapsule.extensions.foo.spec_context.revision");
+            for (const [index, requirement] of boundedArray(context.requirement_ids, "BugCapsule.extensions.foo.spec_context.requirement_ids").entries())
+                boundedString(requirement, `BugCapsule.extensions.foo.spec_context.requirement_ids[${index}]`);
+            for (const [index, task] of boundedArray(context.task_ids, "BugCapsule.extensions.foo.spec_context.task_ids").entries())
+                boundedString(task, `BugCapsule.extensions.foo.spec_context.task_ids[${index}]`);
+            if (context.provenance !== "reporter_observed")
+                throw new Error("BugCapsule.extensions.foo.spec_context.provenance is invalid");
+        }
+    }
+    return capsule;
+}
+export function parseDeliveryReceipt(value) {
+    const receipt = closedObject(value, "DeliveryReceipt", ["schema_version", "receipt_id", "capsule_id", "payload_digest", "accepted_at", "destination", "status", "error"]);
+    if (receipt.schema_version !== "0.1")
+        throw new Error("DeliveryReceipt.schema_version must be 0.1");
+    uuid(receipt.receipt_id, "DeliveryReceipt.receipt_id");
+    uuid(receipt.capsule_id, "DeliveryReceipt.capsule_id");
+    const digest = boundedString(receipt.payload_digest, "DeliveryReceipt.payload_digest");
+    if (!SHA_256_DIGEST.test(digest))
+        throw new Error("DeliveryReceipt.payload_digest must be a lowercase SHA-256 digest");
+    rfc3339(receipt.accepted_at, "DeliveryReceipt.accepted_at");
+    boundedString(receipt.destination, "DeliveryReceipt.destination");
+    if (receipt.status !== "accepted" && receipt.status !== "rejected" && receipt.status !== "retryable")
+        throw new Error("DeliveryReceipt.status is invalid");
+    if (receipt.status === "accepted") {
+        if (receipt.error !== null)
+            throw new Error("accepted receipt requires error to be null");
+    }
+    else {
+        const error = closedObject(receipt.error, "DeliveryReceipt.error", ["code", "message", "retry_after"], ["code", "message"]);
+        boundedString(error.code, "DeliveryReceipt.error.code");
+        boundedString(error.message, "DeliveryReceipt.error.message");
+        if (error.retry_after !== undefined)
+            rfc3339(error.retry_after, "DeliveryReceipt.error.retry_after");
+    }
+    return receipt;
+}

package/dist-public/src/bugCapture.d.ts

@@ -0,0 +1,26 @@
+import { type FieldValue } from "./bugCapsule.js";
+import { type LocalBugRecord } from "./bugReportStore.js";
+import type { BugSpecContext } from "./bugSpecContext.js";
+import { type FailureMark } from "./errorTaxonomy.js";
+export type FailureCaptureInput = {
+    failure: FailureMark;
+    command: string;
+    version: string;
+    specContext?: BugSpecContext;
+    isTest?: boolean;
+};
+export type ManualCaptureInput = {
+    expected?: string;
+    actual?: string;
+    reproduction?: string;
+    command?: string;
+    version: string;
+    specContext?: BugSpecContext;
+};
+/** Secret-redact and path-scrub one diagnostic without ever returning raw text on failure. */
+export declare function scrubDiagnostic(text: string, root: string): FieldValue;
+export declare function captureFailureCapsule(root: string, input: FailureCaptureInput, now?: Date): LocalBugRecord | undefined;
+export type FailureCapsuleCapture = (root: string, input: FailureCaptureInput, now?: Date) => LocalBugRecord | undefined;
+/** Create the once-only capture boundary owned by one main() invocation. */
+export declare function createFailureCapsuleCapture(): FailureCapsuleCapture;
+export declare function captureManualCapsule(root: string, input: ManualCaptureInput, now?: Date): LocalBugRecord;

package/dist-public/src/bugCapture.js

@@ -0,0 +1,251 @@
+import { parseBugCapsule, uuidV7 } from "./bugCapsule.js";
+import { savePending } from "./bugReportStore.js";
+import { errorFingerprint, pages, UsageError } from "./errorTaxonomy.js";
+import { redactText } from "./redactEngine.js";
+const MAX_STRING_LENGTH = 4_096;
+const MAX_PATH_TOKEN_LENGTH = 16_384;
+function bounded(value) {
+    return value.slice(0, MAX_STRING_LENGTH);
+}
+function absolutePathKind(text, index) {
+    const first = text[index];
+    if (/[A-Za-z]/.test(first ?? "") && text[index + 1] === ":" && /[\\/]/.test(text[index + 2] ?? ""))
+        return "windows";
+    if (first === "\\" && text[index + 1] === "\\")
+        return "windows";
+    if (first === "/" && (index === 0 || !/[\p{L}\p{N}._@+-]/u.test(text[index - 1])))
+        return "posix";
+    return undefined;
+}
+function safePathBasename(raw) {
+    const withoutLocation = raw.replace(/:\d+(?::\d+)?$/, "").replace(/[.,;!?]+$/, "");
+    const basename = withoutLocation.split(/[\\/]/).at(-1);
+    return basename && /^[A-Za-z0-9._@+-]{1,255}$/.test(basename) && basename !== "." && basename !== ".."
+        ? basename
+        : undefined;
+}
+function nextSpaceChunkHasSeparator(text, index, closing) {
+    let start = index;
+    while (text[start] === " ")
+        start += 1;
+    let end = start;
+    while (end < text.length && !/\s/.test(text[end]) && (!closing || text[end] !== closing))
+        end += 1;
+    return /[\\/]/.test(text.slice(start, end));
+}
+function basenameLooksComplete(raw) {
+    const basename = safePathBasename(raw);
+    return Boolean(basename && /\.[A-Za-z0-9]{1,16}$/.test(basename));
+}
+function remainderCouldContinueAbsolutePath(text, index) {
+    // The chunk straight after the punctuation may still be this path's next
+    // segment ("customer) records/private/file.txt"), so any separator there
+    // keeps the boundary unproven.
+    if (nextSpaceChunkHasSeparator(text, index, undefined))
+        return true;
+    // Beyond that chunk, only an absolute-looking start (/x, C:\x, \\share)
+    // keeps the boundary unproven. Repo-relative tokens such as src/x.ts,
+    // bin/foo, or discovery/inbox are the vocabulary of a bug report about foo
+    // itself: they say nothing about the reporter's machine and must never
+    // poison an otherwise provable boundary into withholding the field.
+    for (let scan = index; scan < text.length; scan += 1) {
+        if (absolutePathKind(text, scan))
+            return true;
+    }
+    return false;
+}
+function punctuationBoundaryIsProven(text, index) {
+    if (index + 1 === text.length)
+        return true;
+    if (!/\s/.test(text[index + 1]))
+        return false;
+    return !remainderCouldContinueAbsolutePath(text, index + 1);
+}
+/**
+ * Linear path tokenizer. Only absolute/home/drive/UNC starts are treated as
+ * paths; repo-relative tokens (src/x.ts, bin/foo) pass through untouched. An
+ * unprovable boundary on an absolute path withholds the whole field.
+ */
+function scrubAbsolutePaths(text) {
+    const wrappers = { '"': '"', "'": "'", "`": "`", "(": ")", "[": "]", "{": "}" };
+    let result = "";
+    let index = 0;
+    while (index < text.length) {
+        const kind = absolutePathKind(text, index);
+        if (!kind) {
+            result += text[index];
+            index += 1;
+            continue;
+        }
+        const closing = wrappers[text[index - 1] ?? ""];
+        let end = index;
+        while (end < text.length) {
+            const char = text[end];
+            if (char === "\n" || char === "\r" || char === "\t")
+                break;
+            if (closing && char === closing) {
+                if (punctuationBoundaryIsProven(text, end))
+                    break;
+                return undefined;
+            }
+            if (!closing && char === " ") {
+                if (nextSpaceChunkHasSeparator(text, end, closing)) {
+                    end += 1;
+                    continue;
+                }
+                if (!basenameLooksComplete(text.slice(index, end)))
+                    return undefined;
+                break;
+            }
+            if (!closing && /[\])}'"`]/.test(char)) {
+                if (punctuationBoundaryIsProven(text, end))
+                    break;
+                return undefined;
+            }
+            if (!closing && /[,;!?]/.test(char) && (end + 1 === text.length || /\s/.test(text[end + 1])))
+                break;
+            end += 1;
+            if (end - index >= MAX_PATH_TOKEN_LENGTH) {
+                while (end < text.length && !/[\n\r\t]/.test(text[end]))
+                    end += 1;
+                break;
+            }
+        }
+        const basename = safePathBasename(text.slice(index, end));
+        result += basename ? `<path>/${basename}` : "<path>";
+        index = Math.max(end, index + 1);
+    }
+    return result;
+}
+/** Secret-redact and path-scrub one diagnostic without ever returning raw text on failure. */
+export function scrubDiagnostic(text, root) {
+    try {
+        void root;
+        // Order matters: remove complete URLs and credentials before their slashes or
+        // punctuation can be mistaken for filesystem tokens. Each matcher is linear,
+        // whitespace-bounded, and refuses to span prose or surrounding punctuation.
+        let scrubbed = text.replace(/\bhttps?:\/\/[^\s<>"'`]+/gi, "[URL_REDACTED]");
+        scrubbed = scrubbed.replace(/\bBearer[ \t]+[^\s,;'"<>()\[\]{}]+/gi, "Bearer [REDACTED]");
+        const pathScrubbed = scrubAbsolutePaths(scrubbed);
+        if (pathScrubbed === undefined)
+            return { state: "withheld", reason: "ambiguous_path_boundary" };
+        scrubbed = pathScrubbed;
+        return { state: "collected", value: redactText(scrubbed).redactedText };
+    }
+    catch {
+        return { state: "withheld", reason: "scrubbing_failed" };
+    }
+}
+function boundedField(field) {
+    return field.state === "collected" ? { state: "collected", value: bounded(field.value) } : field;
+}
+function absent(reason) {
+    return { state: "not_collected", reason };
+}
+function diagnostic(value, root, reason) {
+    return value === undefined ? absent(reason) : boundedField(scrubDiagnostic(value, root));
+}
+function evidenceState(fields) {
+    if (fields.some((field) => field.state === "withheld"))
+        return "withheld";
+    if (fields.some((field) => field.state === "collected"))
+        return "collected";
+    if (fields.some((field) => field.state === "unavailable"))
+        return "unavailable";
+    return "not_collected";
+}
+function invocationCommand(command) {
+    return bounded(command.startsWith("foo ") ? command : `foo ${command}`);
+}
+function capsuleBase(version, command, occurredAt, specContext) {
+    const boundedVersion = bounded(version);
+    return {
+        schema_version: "0.1",
+        capsule_id: uuidV7(occurredAt.getTime()),
+        occurred_at: occurredAt.toISOString(),
+        producer: { name: "foo", version: boundedVersion },
+        product: { name: "productfoo", component: "cli", version: boundedVersion },
+        invocation: {
+            command: invocationCommand(command),
+            runtime: {
+                node: bounded(process.version.replace(/^v/, "")),
+                platform: bounded(process.platform),
+                arch: bounded(process.arch),
+            },
+        },
+        links: [],
+        extensions: specContext ? { foo: { spec_context: specContext } } : {},
+    };
+}
+export function captureFailureCapsule(root, input, now = new Date()) {
+    if (input.isTest || !pages(input.failure.errorClass))
+        return undefined;
+    try {
+        const message = diagnostic(input.failure.message, root, "failure did not provide a message");
+        const stack = diagnostic(input.failure.stack, root, "failure did not provide a stack");
+        const fingerprint = errorFingerprint(input.failure.errorCode, input.failure.stack);
+        const capsule = parseBugCapsule({
+            ...capsuleBase(input.version, input.command, now, input.specContext),
+            failure: {
+                class: input.failure.errorClass,
+                code: input.failure.errorCode,
+                classifier_version: "0.1",
+                classification: input.failure.errorCode === "E_UNKNOWN" ? "fallback" : "known",
+                message,
+                stack,
+            },
+            report: {
+                expected: absent("automatic failure capture"),
+                actual: absent("automatic failure capture"),
+                reproduction: absent("automatic failure capture"),
+            },
+            evidence: [{ kind: "diagnostic", state: evidenceState([message, stack]), content_type: "text/plain" }],
+            similarity: {
+                version: "0.1",
+                signals: fingerprint ? [{ kind: "error_fingerprint", value: fingerprint }] : [],
+            },
+        });
+        return savePending(root, capsule);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Create the once-only capture boundary owned by one main() invocation. */
+export function createFailureCapsuleCapture() {
+    let captured = false;
+    return (root, input, now = new Date()) => {
+        if (captured)
+            return undefined;
+        const record = captureFailureCapsule(root, input, now);
+        if (record)
+            captured = true;
+        return record;
+    };
+}
+export function captureManualCapsule(root, input, now = new Date()) {
+    if (!input.expected?.trim())
+        throw new UsageError("expected behavior is required", "E_BAD_FLAG");
+    if (!input.actual?.trim())
+        throw new UsageError("actual behavior is required", "E_BAD_FLAG");
+    const expected = boundedField(scrubDiagnostic(input.expected, root));
+    const actual = boundedField(scrubDiagnostic(input.actual, root));
+    const reproduction = input.reproduction?.trim()
+        ? boundedField(scrubDiagnostic(input.reproduction, root))
+        : absent("not provided");
+    const capsule = parseBugCapsule({
+        ...capsuleBase(input.version, input.command ?? "report add", now, input.specContext),
+        failure: {
+            class: "command_error",
+            code: "E_UNKNOWN",
+            classifier_version: "0.1",
+            classification: "fallback",
+            message: absent("manual report"),
+            stack: absent("manual report"),
+        },
+        report: { expected, actual, reproduction },
+        evidence: [{ kind: "user_report", state: evidenceState([expected, actual, reproduction]), content_type: "text/plain" }],
+        similarity: { version: "0.1", signals: [] },
+    });
+    return savePending(root, capsule);
+}

package/dist-public/src/bugOwnerLog.d.ts

@@ -0,0 +1,93 @@
+export type GhCall = {
+    args: string[];
+};
+export type GhExecResult = {
+    ok: boolean;
+    stdout: string;
+    stderr: string;
+};
+export type GhExec = (args: string[]) => GhExecResult;
+export declare const defaultGhExec: GhExec;
+export type BugLogIntake = {
+    /** Candidate issue title (pre-scrub). */
+    title: string;
+    /** Full markdown issue body (pre-scrub). */
+    body: string;
+    /** Text evaluated for dedupe matching. */
+    search_text: string;
+    /** Companion issue refs, e.g. ["#528", "#529"]. */
+    refs: string[];
+};
+export type BugLogMatch = {
+    issue_number: number;
+    issue_url: string;
+    issue_title: string;
+    issue_state: string;
+    score: number;
+    matched_terms: string[];
+};
+export type BugLogStatus = "reproduced" | "filed" | "refused" | "retryable";
+export type BugLogResult = {
+    schema_version: "0.1";
+    status: BugLogStatus;
+    repo: string | null;
+    issue_number: number | null;
+    issue_url: string | null;
+    match: BugLogMatch | null;
+    withheld: string | null;
+    errors: Array<{
+        code: string;
+        message: string;
+    }>;
+    next_actions: string[];
+};
+/** Per-run bounded-autonomy state (R-006): creation ceiling + title-hash guard. */
+export type BugLogSession = {
+    created: number;
+    max_creates: number;
+    title_hashes: Set<string>;
+};
+/** Recent auto-creations for the configured owner repo, within the rolling window. */
+export declare function recentBugCreateCount(root: string, env: NodeJS.ProcessEnv, now?: number): number;
+/** Records one auto-creation so the next invocation's ceiling counts it (R-006/RISK-002). */
+export declare function recordBugCreate(root: string, env: NodeJS.ProcessEnv, repo: string, now?: number): void;
+export declare function newBugLogSession(env: NodeJS.ProcessEnv, root?: string): BugLogSession;
+type OwnerIssue = {
+    number: number;
+    title: string;
+    state: string;
+    url: string;
+    body: string;
+};
+export type DedupeVerdict = CommentVerdict | CreateVerdict;
+export type CommentVerdict = {
+    decision: "comment";
+    match: BugLogMatch;
+};
+/** Only `evaluateBugDedupe` constructs this; `createOwnerIssue` requires it. */
+export type CreateVerdict = {
+    decision: "create";
+    evaluated_issues: number;
+    proof: "dedupe_evaluated";
+};
+export declare function evaluateBugDedupe(intake: BugLogIntake, issues: OwnerIssue[]): DedupeVerdict;
+export declare function buildBugLogIntake(fields: {
+    expected: string;
+    actual: string;
+    reproduction?: string;
+    suggested?: string;
+    refs?: string[];
+}): BugLogIntake;
+/** Seeds the engine from a discovery inbox signal: headline → title candidate,
+ *  paraphrase → evidence body with provenance. Signals are already sanitized
+ *  paraphrases; provenance names the finding, call date, and attribution basis. */
+export declare function buildSignalBugIntake(record: Record<string, unknown>): BugLogIntake;
+export declare function bugLogRefusal(code: string, message: string, nextActions: string[], repo?: string | null, withheld?: string | null): BugLogResult;
+export declare function runBugLog(options: {
+    env: NodeJS.ProcessEnv;
+    gh: GhExec;
+    session: BugLogSession;
+    intake: BugLogIntake;
+    root: string;
+}): BugLogResult;
+export {};