youmd 0.10.0 → 0.10.2

package/dist/lib/brain/proposal.js

@@ -0,0 +1,694 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROJECT_BRAIN_PROPOSAL_VERSION = exports.PROJECT_BRAIN_PROPOSAL_SCHEMA = exports.PROJECT_BRAIN_OVERRIDE_VERSION = void 0;
+exports.validateProjectBrainPatch = validateProjectBrainPatch;
+exports.validateProjectBrainUnifiedDiffPatch = validateProjectBrainUnifiedDiffPatch;
+exports.validateProjectBrainProposal = validateProjectBrainProposal;
+exports.proposeProjectBrainAdoption = proposeProjectBrainAdoption;
+exports.importProjectBrainOverrides = importProjectBrainOverrides;
+const redact_1 = require("../redact");
+const canonical_1 = require("./canonical");
+exports.PROJECT_BRAIN_OVERRIDE_VERSION = "you-md/project-brain-override/v1";
+exports.PROJECT_BRAIN_PROPOSAL_SCHEMA = "https://you.md/schemas/project-brain-proposal/v1";
+exports.PROJECT_BRAIN_PROPOSAL_VERSION = "you-md/project-brain-proposal/v1";
+const PROJECT_REF_PATTERN = /^project:[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/;
+const REVISION_PATTERN = /^sha256:[a-f0-9]{64}$/;
+const OVERRIDE_SOURCE_PATTERN = /^(?:overrides|notes)\/[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*\.json$/;
+const ARTIFACT_REF_PATTERN = /^artifact:[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?\/[a-z0-9][a-z0-9._-]{0,95}$/;
+const FORBIDDEN_SEGMENTS = new Set(["__proto__", "prototype", "constructor"]);
+const MAX_PATCH_OPERATIONS = 100;
+const MAX_PATCH_BYTES = 256 * 1024;
+const APPROVAL_BINDINGS = [
+    "proposalRef",
+    "projectRef",
+    "machineRef",
+    "workspaceRef",
+    "baseRevision",
+    "target.baseContentHash",
+    "source.sourceRevision",
+    "patchFormat",
+    "patchDigest",
+];
+function proposalError(sourceRef, code, message, operationIndex) {
+    return operationIndex === undefined ? { sourceRef, code, message } : { sourceRef, code, message, operationIndex };
+}
+function normalizeJson(value, seen = new Set()) {
+    if (value === null || typeof value === "boolean" || typeof value === "string")
+        return value;
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new TypeError("project brain patches reject non-finite numbers");
+        return Object.is(value, -0) ? 0 : value;
+    }
+    if (Array.isArray(value)) {
+        if (seen.has(value))
+            throw new TypeError("project brain patches reject cyclic values");
+        seen.add(value);
+        const normalized = value.map((item) => normalizeJson(item, seen));
+        seen.delete(value);
+        return normalized;
+    }
+    if (value && typeof value === "object") {
+        if (seen.has(value))
+            throw new TypeError("project brain patches reject cyclic values");
+        seen.add(value);
+        const normalized = Object.create(null);
+        for (const key of Object.keys(value).sort()) {
+            if (FORBIDDEN_SEGMENTS.has(key))
+                throw new TypeError("project brain patches reject unsafe object keys");
+            const child = value[key];
+            if (child === undefined)
+                throw new TypeError("project brain patches reject undefined values");
+            normalized[key] = normalizeJson(child, seen);
+        }
+        seen.delete(value);
+        return normalized;
+    }
+    throw new TypeError(`project brain patches reject ${typeof value} values`);
+}
+function cloneJson(value) {
+    return normalizeJson(value);
+}
+function digest(value) {
+    return `sha256:${(0, canonical_1.sha256)((0, canonical_1.canonicalize)(value))}`;
+}
+function safeSecretScan(value) {
+    const serialized = JSON.stringify(value).replace(/(?:(?:machine|repository|worktree|branch):sha256:|(?:scan|workspace|sha256|heuristic):|proposal:brain\/)[a-f0-9]{64}/g, "[OPAQUE_HASH]");
+    return (0, redact_1.redactText)(serialized).hits === 0;
+}
+function parsePointer(pointer) {
+    if (typeof pointer !== "string" || pointer.length > 500)
+        return null;
+    if (pointer === "")
+        return [];
+    if (!pointer.startsWith("/"))
+        return null;
+    const encoded = pointer.slice(1).split("/");
+    if (encoded.length > 100)
+        return null;
+    const decoded = [];
+    for (const segment of encoded) {
+        if (/~(?:[^01]|$)/.test(segment))
+            return null;
+        const value = segment.replace(/~1/g, "/").replace(/~0/g, "~");
+        if (FORBIDDEN_SEGMENTS.has(value))
+            return null;
+        decoded.push(value);
+    }
+    return decoded;
+}
+function own(record, key) {
+    return Object.prototype.hasOwnProperty.call(record, key);
+}
+function arrayIndex(segment, length, allowEnd) {
+    if (!/^(?:0|[1-9][0-9]*)$/.test(segment))
+        return null;
+    const index = Number(segment);
+    if (!Number.isSafeInteger(index) || index < 0 || index > length || (!allowEnd && index === length))
+        return null;
+    return index;
+}
+function state(present, value) {
+    return present ? { present: true, value: cloneJson(value) } : { present: false };
+}
+function normalizePatch(raw, sourceRef) {
+    if (!Array.isArray(raw) || raw.length === 0 || raw.length > MAX_PATCH_OPERATIONS) {
+        return { errors: [proposalError(sourceRef, "invalid_patch", "patch must contain between 1 and 100 operations")] };
+    }
+    let rawBytes;
+    try {
+        rawBytes = Buffer.byteLength(JSON.stringify(raw), "utf8");
+    }
+    catch {
+        rawBytes = MAX_PATCH_BYTES + 1;
+    }
+    if (rawBytes > MAX_PATCH_BYTES)
+        return { errors: [proposalError(sourceRef, "invalid_patch", "patch exceeds the safe size budget")] };
+    const patch = [];
+    const errors = [];
+    for (const [index, candidate] of raw.entries()) {
+        if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) {
+            errors.push(proposalError(sourceRef, "invalid_patch", "patch operation must be an object", index));
+            continue;
+        }
+        const operation = candidate;
+        const op = operation.op;
+        const pointer = parsePointer(operation.path);
+        const allowedKeys = op === "remove" ? new Set(["op", "path"]) : new Set(["op", "path", "value"]);
+        if (!new Set(["add", "remove", "replace", "test"]).has(String(op)) || !pointer
+            || Object.keys(operation).some((key) => !allowedKeys.has(key))) {
+            errors.push(proposalError(sourceRef, "unsafe_patch", "patch operation or JSON pointer is unsupported", index));
+            continue;
+        }
+        if (op === "remove") {
+            if ("value" in operation)
+                errors.push(proposalError(sourceRef, "invalid_patch", "remove operations cannot contain a value", index));
+            else
+                patch.push({ op: "remove", path: String(operation.path) });
+            continue;
+        }
+        if (!("value" in operation)) {
+            errors.push(proposalError(sourceRef, "invalid_patch", `${String(op)} operations require an exact value`, index));
+            continue;
+        }
+        try {
+            patch.push({ op: op, path: String(operation.path), value: normalizeJson(operation.value) });
+        }
+        catch {
+            errors.push(proposalError(sourceRef, "invalid_patch", "patch value is not safe canonical JSON", index));
+        }
+    }
+    if (!errors.length && !safeSecretScan(patch))
+        errors.push(proposalError(sourceRef, "secret_detected", "patch contains a secret or private-data pattern"));
+    return errors.length ? { errors } : { patch, errors: [] };
+}
+function resolveParent(document, segments) {
+    if (segments.length === 0)
+        return null;
+    let current = document;
+    for (const segment of segments.slice(0, -1)) {
+        if (Array.isArray(current)) {
+            const index = arrayIndex(segment, current.length, false);
+            if (index === null)
+                return null;
+            current = current[index];
+        }
+        else if (current && typeof current === "object") {
+            if (!own(current, segment))
+                return null;
+            current = current[segment];
+        }
+        else
+            return null;
+    }
+    return Array.isArray(current) || (current && typeof current === "object")
+        ? { parent: current, key: segments.at(-1) }
+        : null;
+}
+/** Pure RFC6902-style validation and evaluation. This function has no filesystem capability. */
+function validateProjectBrainPatch(base, rawPatch, sourceRef = "proposal:input") {
+    let document;
+    try {
+        document = normalizeJson(base);
+    }
+    catch {
+        return { valid: false, errors: [proposalError(sourceRef, "invalid_patch", "base document is not canonical JSON")] };
+    }
+    const before = cloneJson(document);
+    const normalized = normalizePatch(rawPatch, sourceRef);
+    if (!normalized.patch)
+        return { valid: false, errors: normalized.errors };
+    const operations = [];
+    const errors = [];
+    for (const [index, operation] of normalized.patch.entries()) {
+        const segments = parsePointer(operation.path);
+        if (segments.length === 0) {
+            const beforeState = state(true, document);
+            if (operation.op === "remove") {
+                errors.push(proposalError(sourceRef, "unsafe_patch", "removing the root document is not supported", index));
+                break;
+            }
+            if (operation.op === "test") {
+                if ((0, canonical_1.canonicalize)(document) !== (0, canonical_1.canonicalize)(operation.value)) {
+                    errors.push(proposalError(sourceRef, "patch_test_failed", "patch test does not match the exact base document", index));
+                    break;
+                }
+            }
+            else
+                document = cloneJson(operation.value);
+            operations.push({ index, op: operation.op, path: operation.path, before: beforeState, after: state(true, document) });
+            continue;
+        }
+        const resolved = resolveParent(document, segments);
+        if (!resolved) {
+            errors.push(proposalError(sourceRef, "invalid_patch", "patch parent does not exist in the exact base document", index));
+            break;
+        }
+        const { parent, key } = resolved;
+        if (Array.isArray(parent)) {
+            if (operation.op === "add") {
+                const insertion = key === "-" ? parent.length : arrayIndex(key, parent.length, true);
+                if (insertion === null) {
+                    errors.push(proposalError(sourceRef, "invalid_patch", "array add index is invalid", index));
+                    break;
+                }
+                parent.splice(insertion, 0, cloneJson(operation.value));
+                operations.push({ index, op: operation.op, path: operation.path, before: state(false), after: state(true, operation.value) });
+                continue;
+            }
+            const target = arrayIndex(key, parent.length, false);
+            if (target === null) {
+                errors.push(proposalError(sourceRef, "invalid_patch", "array patch target does not exist", index));
+                break;
+            }
+            const oldValue = cloneJson(parent[target]);
+            if (operation.op === "test") {
+                if ((0, canonical_1.canonicalize)(oldValue) !== (0, canonical_1.canonicalize)(operation.value)) {
+                    errors.push(proposalError(sourceRef, "patch_test_failed", "patch test does not match the exact base value", index));
+                    break;
+                }
+                operations.push({ index, op: operation.op, path: operation.path, before: state(true, oldValue), after: state(true, oldValue) });
+            }
+            else if (operation.op === "remove") {
+                parent.splice(target, 1);
+                operations.push({ index, op: operation.op, path: operation.path, before: state(true, oldValue), after: state(false) });
+            }
+            else {
+                parent[target] = cloneJson(operation.value);
+                operations.push({ index, op: operation.op, path: operation.path, before: state(true, oldValue), after: state(true, operation.value) });
+            }
+            continue;
+        }
+        const exists = own(parent, key);
+        const oldValue = exists ? cloneJson(parent[key]) : undefined;
+        if (operation.op === "add") {
+            parent[key] = cloneJson(operation.value);
+            operations.push({ index, op: operation.op, path: operation.path, before: state(exists, oldValue), after: state(true, operation.value) });
+        }
+        else if (!exists) {
+            errors.push(proposalError(sourceRef, "invalid_patch", "object patch target does not exist", index));
+            break;
+        }
+        else if (operation.op === "test") {
+            if ((0, canonical_1.canonicalize)(oldValue) !== (0, canonical_1.canonicalize)(operation.value)) {
+                errors.push(proposalError(sourceRef, "patch_test_failed", "patch test does not match the exact base value", index));
+                break;
+            }
+            operations.push({ index, op: operation.op, path: operation.path, before: state(true, oldValue), after: state(true, oldValue) });
+        }
+        else if (operation.op === "remove") {
+            delete parent[key];
+            operations.push({ index, op: operation.op, path: operation.path, before: state(true, oldValue), after: state(false) });
+        }
+        else {
+            parent[key] = cloneJson(operation.value);
+            operations.push({ index, op: operation.op, path: operation.path, before: state(true, oldValue), after: state(true, operation.value) });
+        }
+    }
+    if (errors.length)
+        return { valid: false, errors };
+    const diff = {
+        format: "rfc6902",
+        beforeDigest: digest(before),
+        afterDigest: digest(document),
+        operations,
+    };
+    return { valid: true, errors: [], patch: normalized.patch, patchDigest: digest(normalized.patch), result: document, diff };
+}
+function safeRelativeTextPath(value) {
+    if (typeof value !== "string" || value.length < 1 || value.length > 500 || value.startsWith("/")
+        || /^[A-Za-z]:/.test(value) || value.includes("\\") || value.includes("//") || value.endsWith("/"))
+        return false;
+    return value.split("/").every((segment) => segment && segment !== "." && segment !== "..");
+}
+function renderUnifiedDiff(oldPath, newPath, hunks) {
+    const lines = [`--- a/${oldPath}`, `+++ b/${newPath}`];
+    for (const hunk of hunks) {
+        lines.push(`@@ -${hunk.oldStart},${hunk.oldLines} +${hunk.newStart},${hunk.newLines} @@`, ...hunk.lines);
+    }
+    return `${lines.join("\n")}\n`;
+}
+/** Strictly normalize the hosted text variant without converting it to RFC6902. */
+function validateProjectBrainUnifiedDiffPatch(raw, sourceRef = "proposal:input") {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        return { valid: false, errors: [proposalError(sourceRef, "invalid_patch", "unified diff patch must be an object")] };
+    }
+    const input = raw;
+    if (Object.keys(input).some((key) => !new Set(["text", "oldPath", "newPath", "hunks"]).has(key))
+        || typeof input.text !== "string" || Buffer.byteLength(input.text, "utf8") > 1024 * 1024
+        || !safeRelativeTextPath(input.oldPath) || !safeRelativeTextPath(input.newPath)
+        || !Array.isArray(input.hunks) || input.hunks.length < 1 || input.hunks.length > 100) {
+        return { valid: false, errors: [proposalError(sourceRef, "invalid_patch", "unified diff shape or path is invalid")] };
+    }
+    const hunks = [];
+    for (const [index, rawHunk] of input.hunks.entries()) {
+        if (!rawHunk || typeof rawHunk !== "object" || Array.isArray(rawHunk)) {
+            return { valid: false, errors: [proposalError(sourceRef, "invalid_patch", "unified diff hunk must be an object", index)] };
+        }
+        const hunk = rawHunk;
+        if (Object.keys(hunk).some((key) => !new Set(["oldStart", "oldLines", "newStart", "newLines", "lines"]).has(key))
+            || !Number.isInteger(hunk.oldStart) || Number(hunk.oldStart) < 0
+            || !Number.isInteger(hunk.oldLines) || Number(hunk.oldLines) < 0
+            || !Number.isInteger(hunk.newStart) || Number(hunk.newStart) < 0
+            || !Number.isInteger(hunk.newLines) || Number(hunk.newLines) < 0
+            || !Array.isArray(hunk.lines) || hunk.lines.some((line) => typeof line !== "string" || !/^(?: |\+|-|\\)/.test(line))) {
+            return { valid: false, errors: [proposalError(sourceRef, "invalid_patch", "unified diff hunk is invalid", index)] };
+        }
+        const oldCount = hunk.lines.filter((line) => typeof line === "string" && /^[ -]/.test(line)).length;
+        const newCount = hunk.lines.filter((line) => typeof line === "string" && /^[ +]/.test(line)).length;
+        if (oldCount !== hunk.oldLines || newCount !== hunk.newLines) {
+            return { valid: false, errors: [proposalError(sourceRef, "invalid_patch", "unified diff hunk line counts do not match", index)] };
+        }
+        hunks.push({
+            oldStart: Number(hunk.oldStart), oldLines: Number(hunk.oldLines),
+            newStart: Number(hunk.newStart), newLines: Number(hunk.newLines),
+            lines: [...hunk.lines],
+        });
+    }
+    const patch = { text: input.text, oldPath: input.oldPath, newPath: input.newPath, hunks };
+    if (patch.text !== renderUnifiedDiff(patch.oldPath, patch.newPath, patch.hunks)) {
+        return { valid: false, errors: [proposalError(sourceRef, "invalid_patch", "unified diff text does not match its normalized hunks")] };
+    }
+    if (!safeSecretScan(patch))
+        return { valid: false, errors: [proposalError(sourceRef, "secret_detected", "unified diff contains a secret or private-data pattern")] };
+    return { valid: true, errors: [], patch, patchDigest: digest(normalizeJson(patch)) };
+}
+/** Validate a transport proposal envelope without approving or applying it. */
+function validateProjectBrainProposal(value) {
+    const sourceRef = value && typeof value === "object" && typeof value.proposalRef === "string"
+        ? String(value.proposalRef)
+        : "proposal:input";
+    let normalized;
+    try {
+        normalized = normalizeJson(value);
+    }
+    catch {
+        return { valid: false, errors: [proposalError(sourceRef, "invalid_proposal", "proposal is not safe canonical JSON")] };
+    }
+    if (!normalized || typeof normalized !== "object" || Array.isArray(normalized)) {
+        return { valid: false, errors: [proposalError(sourceRef, "invalid_proposal", "proposal must be an object")] };
+    }
+    const proposal = normalized;
+    const record = normalized;
+    const errors = [];
+    const requiredKeys = new Set([
+        "$schema", "schemaVersion", "kind", "proposalRef", "proposalType", "projectRef", "machineRef", "workspaceRef",
+        "baseRevision", "requestedCapability", "rationale", "status", "target", "patchFormat", "patchDigest", "patch", "diff",
+        "approval", "source",
+    ]);
+    if (Object.keys(record).length !== requiredKeys.size || Object.keys(record).some((key) => !requiredKeys.has(key))
+        || proposal.$schema !== exports.PROJECT_BRAIN_PROPOSAL_SCHEMA || proposal.schemaVersion !== exports.PROJECT_BRAIN_PROPOSAL_VERSION
+        || proposal.kind !== "project-brain-proposal" || proposal.status !== "proposed"
+        || !PROJECT_REF_PATTERN.test(proposal.projectRef) || !/^machine:sha256:[a-f0-9]{64}$/.test(proposal.machineRef)
+        || !/^workspace:[a-f0-9]{64}$/.test(proposal.workspaceRef) || !REVISION_PATTERN.test(proposal.baseRevision)
+        || typeof proposal.rationale !== "string" || proposal.rationale.trim().length < 3 || proposal.rationale.length > 1000
+        || !proposal.target || proposal.target.humanOwned !== true || !ARTIFACT_REF_PATTERN.test(proposal.target.artifactRef)
+        || !REVISION_PATTERN.test(proposal.target.baseContentHash) || !proposal.source
+        || !/^(?:sha256|heuristic|git):[A-Za-z0-9._-]{7,128}$/.test(proposal.source.sourceRevision)) {
+        errors.push(proposalError(sourceRef, "invalid_proposal", "proposal envelope or identity is invalid"));
+    }
+    if (!safeSecretScan(proposal))
+        errors.push(proposalError(sourceRef, "secret_detected", "proposal contains a secret or private-data pattern"));
+    if (!proposal.diff || proposal.target?.baseContentHash !== proposal.diff.beforeDigest || proposal.patchFormat !== proposal.diff.format) {
+        errors.push(proposalError(sourceRef, "invalid_proposal", "proposal target or patch format is not bound to the exact diff"));
+    }
+    if (proposal.patchFormat === "rfc6902") {
+        const patch = normalizePatch(proposal.patch, sourceRef);
+        if (!patch.patch)
+            errors.push(...patch.errors);
+        else if (proposal.patchDigest !== digest(patch.patch))
+            errors.push(proposalError(sourceRef, "patch_digest_mismatch", "proposal patch digest does not match RFC6902 operations"));
+        if (!proposal.diff || !Array.isArray(proposal.diff.operations) || !Array.isArray(proposal.patch)
+            || proposal.diff.operations.length !== proposal.patch.length
+            || proposal.diff.operations.some((operation, index) => operation.index !== index
+                || operation.op !== proposal.patch[index]?.op || operation.path !== proposal.patch[index]?.path)) {
+            errors.push(proposalError(sourceRef, "invalid_proposal", "RFC6902 diff operations do not match the exact patch"));
+        }
+    }
+    else if (proposal.patchFormat === "unified_diff") {
+        const patch = validateProjectBrainUnifiedDiffPatch(proposal.patch, sourceRef);
+        if (!patch.valid)
+            errors.push(...patch.errors);
+        else if (proposal.patchDigest !== patch.patchDigest)
+            errors.push(proposalError(sourceRef, "patch_digest_mismatch", "proposal patch digest does not match the normalized unified diff"));
+        if (!proposal.diff || JSON.stringify(proposal.diff.hunks) !== JSON.stringify(proposal.patch.hunks)) {
+            errors.push(proposalError(sourceRef, "invalid_proposal", "unified diff evidence does not match the normalized patch"));
+        }
+    }
+    else
+        errors.push(proposalError(sourceRef, "invalid_proposal", "proposal patchFormat is unsupported"));
+    if (!proposal.approval || proposal.approval.required !== true || proposal.approval.policy !== "fresh_exact_patch"
+        || proposal.approval.reusable !== false || proposal.approval.maxAgeSeconds !== 900
+        || JSON.stringify(proposal.approval.bindingFields) !== JSON.stringify(APPROVAL_BINDINGS)) {
+        errors.push(proposalError(sourceRef, "approval_binding_mismatch", "proposal requires a fresh approval bound to every exact identity and patch field"));
+    }
+    const { proposalRef: _proposalRef, ...preimage } = proposal;
+    if (proposal.proposalRef !== `proposal:brain/${(0, canonical_1.sha256)((0, canonical_1.canonicalize)(preimage))}`) {
+        errors.push(proposalError(sourceRef, "proposal_ref_mismatch", "proposalRef does not match the canonical proposal envelope"));
+    }
+    const typeValid = proposal.proposalType === "descriptor_adoption"
+        ? proposal.requestedCapability === "brain.descriptor.adopt" && proposal.patchFormat === "rfc6902"
+            && proposal.target.kind === "repository_file" && proposal.target.path === ".you-project" && proposal.target.exists === false
+        : proposal.proposalType === "personal_override"
+            ? proposal.requestedCapability === "brain.override.propose" && proposal.patchFormat === "rfc6902"
+                && proposal.target.kind === "project_snapshot" && proposal.target.path === undefined && proposal.target.exists === true
+            : proposal.proposalType === "artifact_update"
+                && proposal.requestedCapability === "brain.artifact.update" && proposal.patchFormat === "unified_diff"
+                && proposal.target.kind === "repository_file" && typeof proposal.target.path === "string" && proposal.target.exists === true;
+    if (!typeValid)
+        errors.push(proposalError(sourceRef, "invalid_proposal", "proposal type, capability, target, and patch format are inconsistent"));
+    return errors.length ? { valid: false, errors } : { valid: true, errors: [], proposal };
+}
+function buildProposal(seed) {
+    if (!PROJECT_REF_PATTERN.test(seed.projectRef) || !/^machine:sha256:[a-f0-9]{64}$/.test(seed.machineRef)
+        || !/^workspace:[a-f0-9]{64}$/.test(seed.workspaceRef)
+        || !REVISION_PATTERN.test(seed.baseRevision) || !ARTIFACT_REF_PATTERN.test(seed.target.artifactRef)) {
+        throw new TypeError("project brain proposal identity is invalid");
+    }
+    const preimage = {
+        $schema: exports.PROJECT_BRAIN_PROPOSAL_SCHEMA,
+        schemaVersion: exports.PROJECT_BRAIN_PROPOSAL_VERSION,
+        kind: "project-brain-proposal",
+        ...seed,
+        status: "proposed",
+        approval: {
+            required: true,
+            policy: "fresh_exact_patch",
+            reusable: false,
+            maxAgeSeconds: 900,
+            bindingFields: APPROVAL_BINDINGS,
+        },
+    };
+    return { ...preimage, proposalRef: `proposal:brain/${(0, canonical_1.sha256)((0, canonical_1.canonicalize)(preimage))}` };
+}
+function stripFactProvenance(project) {
+    return project.artifacts.map((artifact) => ({
+        artifactRef: artifact.artifactRef,
+        subjectRef: artifact.subjectRef,
+        kind: artifact.kind,
+        path: artifact.path,
+        owner: artifact.owner,
+        authority: artifact.authority,
+        writePolicy: "read_only",
+        provenance: {
+            source: artifact.provenance.source,
+            sourceRef: artifact.provenance.sourceRef,
+            sourceRevision: artifact.provenance.sourceRevision,
+            indexedAt: artifact.provenance.indexedAt,
+            freshness: artifact.provenance.freshness,
+        },
+    }));
+}
+const PROJECT_REVISION_FIELDS = [
+    "$schema", "schemaVersion", "kind", "projectRef", "slug", "name", "contextRoot",
+    "agentRoots", "artifacts", "relationships", "writePolicy", "generatedExcludes", "provenance",
+];
+function withoutVolatile(value) {
+    if (Array.isArray(value))
+        return value.map(withoutVolatile);
+    if (!value || typeof value !== "object")
+        return value;
+    const result = Object.create(null);
+    for (const [key, child] of Object.entries(value))
+        if (key !== "indexedAt" && key !== "checkedAt")
+            result[key] = withoutVolatile(child);
+    return result;
+}
+function adoptionDescriptor(scan, project, name) {
+    const slug = project.projectRef.slice("project:".length);
+    const descriptor = {
+        $schema: "https://you.md/schemas/project-brain/v1",
+        schemaVersion: "you-md/project-brain/v1",
+        kind: "project",
+        projectRef: project.projectRef,
+        slug,
+        name: name?.trim() || slug.split("-").map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" "),
+        contextRoot: project.contextRoot,
+        agentRoots: project.artifacts.filter((artifact) => artifact.kind === "agent").map((artifact) => artifact.path),
+        artifacts: stripFactProvenance(project),
+        relationships: [],
+        writePolicy: { default: "read_only", managedPaths: [], taskWrite: { enabled: false } },
+        generatedExcludes: [...scan.generatedExcludes],
+        provenance: {
+            source: project.management === "legacy-adopted" ? "legacy-adoption" : "declared",
+            descriptorPath: ".you-project",
+            sourceRevision: scan.revision.digest,
+            indexedAt: project.provenance.indexedAt,
+            freshness: project.provenance.freshness,
+        },
+    };
+    const preimage = Object.fromEntries(PROJECT_REVISION_FIELDS.map((field) => [field, withoutVolatile(descriptor[field])]));
+    descriptor.revision = {
+        canonicalization: "RFC8785",
+        hashAlgorithm: "SHA-256",
+        preimageFields: [...PROJECT_REVISION_FIELDS],
+        volatileExclusions: [
+            "provenance.indexedAt",
+            "provenance.freshness.checkedAt",
+            "artifacts[*].provenance.indexedAt",
+            "artifacts[*].provenance.freshness.checkedAt",
+        ],
+        digest: `sha256:${(0, canonical_1.sha256)((0, canonical_1.canonicalize)(preimage))}`,
+    };
+    return normalizeJson(descriptor);
+}
+/** Generate review-only `.you-project` adoption proposals. No target file is created or changed. */
+function proposeProjectBrainAdoption(scan, options = {}) {
+    const proposals = [];
+    const errors = [];
+    const projects = scan.projects.filter((project) => !options.projectRef || project.projectRef === options.projectRef);
+    if (options.projectRef && projects.length === 0)
+        errors.push(proposalError(options.projectRef, "unknown_project", "project is not present in the exact scan"));
+    for (const project of projects) {
+        if (project.management === "declared" || project.descriptorPath === ".you-project") {
+            errors.push(proposalError(project.projectRef, "not_adoptable", "project already has a declared .you-project descriptor"));
+            continue;
+        }
+        if (project.artifacts.length === 0) {
+            errors.push(proposalError(project.projectRef, "not_adoptable", "project has no attributable artifacts for descriptor adoption"));
+            continue;
+        }
+        const descriptor = adoptionDescriptor(scan, project, options.name);
+        const patchResult = validateProjectBrainPatch(null, [{ op: "add", path: "", value: descriptor }], project.projectRef);
+        if (!patchResult.valid || !patchResult.patch || !patchResult.patchDigest || !patchResult.diff) {
+            errors.push(...patchResult.errors);
+            continue;
+        }
+        const slug = project.projectRef.slice("project:".length);
+        proposals.push(buildProposal({
+            proposalType: "descriptor_adoption",
+            projectRef: project.projectRef,
+            machineRef: scan.workspaceIdentity.machineRef,
+            workspaceRef: scan.workspaceRef,
+            baseRevision: scan.revision.digest,
+            requestedCapability: "brain.descriptor.adopt",
+            patchFormat: "rfc6902",
+            patchDigest: patchResult.patchDigest,
+            rationale: options.rationale?.trim() || `Adopt ${project.projectRef} with a reviewable .you-project descriptor.`,
+            target: {
+                kind: "repository_file",
+                artifactRef: `artifact:${slug}/project-descriptor`,
+                path: ".you-project",
+                owner: "repository",
+                authority: "canonical",
+                humanOwned: true,
+                exists: false,
+                baseContentHash: digest(null),
+            },
+            patch: patchResult.patch,
+            diff: patchResult.diff,
+            source: {
+                kind: project.management === "legacy-adopted" ? "legacy_marker" : "heuristic_scan",
+                sourceRef: project.provenance.sourceRef,
+                sourceRevision: project.provenance.sourceRevision,
+                ...(project.legacyMarkerPath ? { path: project.legacyMarkerPath } : {}),
+            },
+        }));
+    }
+    proposals.sort((a, b) => a.proposalRef.localeCompare(b.proposalRef));
+    errors.sort((a, b) => a.sourceRef.localeCompare(b.sourceRef) || a.code.localeCompare(b.code));
+    return { proposals, errors };
+}
+function parseOverride(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const input = value;
+    const keys = new Set(["$schema", "schemaVersion", "kind", "projectRef", "baseRevision", "rationale", "patch"]);
+    if (Object.keys(input).some((key) => !keys.has(key))
+        || input.$schema !== "https://you.md/schemas/project-brain-override/v1"
+        || input.schemaVersion !== exports.PROJECT_BRAIN_OVERRIDE_VERSION
+        || input.kind !== "project-brain-override"
+        || typeof input.projectRef !== "string" || !PROJECT_REF_PATTERN.test(input.projectRef)
+        || typeof input.baseRevision !== "string" || !REVISION_PATTERN.test(input.baseRevision)
+        || typeof input.rationale !== "string" || input.rationale.trim().length < 3 || input.rationale.length > 1000
+        || !Array.isArray(input.patch))
+        return null;
+    return {
+        $schema: input.$schema,
+        schemaVersion: input.schemaVersion,
+        kind: input.kind,
+        projectRef: input.projectRef,
+        baseRevision: input.baseRevision,
+        rationale: input.rationale.trim(),
+        patch: input.patch,
+    };
+}
+/** Import explicit personal overrides as exact proposals only. No patch is applied here. */
+function importProjectBrainOverrides(scan, sources) {
+    const proposals = [];
+    const errors = [];
+    const addError = (sourcePath, error) => {
+        errors.push({ ...error, sourcePath });
+    };
+    for (const source of [...sources].sort((a, b) => a.sourcePath.localeCompare(b.sourcePath))) {
+        if (!OVERRIDE_SOURCE_PATTERN.test(source.sourcePath) || source.sourcePath.includes("..") || source.sourcePath.includes("\\")) {
+            addError(source.sourcePath, proposalError(source.sourcePath, "unsafe_source_path", "override imports must be explicit JSON under overrides/ or notes/"));
+            continue;
+        }
+        if (!safeSecretScan(source.content)) {
+            addError(source.sourcePath, proposalError(source.sourcePath, "secret_detected", "override content contains a secret or private-data pattern"));
+            continue;
+        }
+        let raw;
+        try {
+            raw = JSON.parse(source.content);
+        }
+        catch {
+            addError(source.sourcePath, proposalError(source.sourcePath, "invalid_json", "override content is not valid JSON"));
+            continue;
+        }
+        const override = parseOverride(raw);
+        if (!override) {
+            addError(source.sourcePath, proposalError(source.sourcePath, "invalid_override", "override does not match the proposal-only v1 contract"));
+            continue;
+        }
+        const project = scan.projects.find((candidate) => candidate.projectRef === override.projectRef);
+        if (!project) {
+            addError(source.sourcePath, proposalError(source.sourcePath, "unknown_project", "override projectRef is not present in this scan"));
+            continue;
+        }
+        if (override.baseRevision !== scan.revision.digest) {
+            addError(source.sourcePath, proposalError(source.sourcePath, "stale_base", "override baseRevision does not match the exact scan revision"));
+            continue;
+        }
+        const patchResult = validateProjectBrainPatch(project, override.patch, source.sourcePath);
+        if (!patchResult.valid || !patchResult.patch || !patchResult.patchDigest || !patchResult.diff) {
+            for (const error of patchResult.errors)
+                addError(source.sourcePath, error);
+            continue;
+        }
+        const slug = project.projectRef.slice("project:".length);
+        proposals.push(buildProposal({
+            proposalType: "personal_override",
+            projectRef: project.projectRef,
+            machineRef: scan.workspaceIdentity.machineRef,
+            workspaceRef: scan.workspaceRef,
+            baseRevision: scan.revision.digest,
+            requestedCapability: "brain.override.propose",
+            patchFormat: "rfc6902",
+            patchDigest: patchResult.patchDigest,
+            rationale: override.rationale,
+            target: {
+                kind: "project_snapshot",
+                artifactRef: `artifact:${slug}/project-snapshot`,
+                owner: project.provenance.owner,
+                authority: project.provenance.authority,
+                humanOwned: true,
+                exists: true,
+                baseContentHash: digest(normalizeJson(project)),
+            },
+            patch: patchResult.patch,
+            diff: patchResult.diff,
+            source: {
+                kind: "override",
+                sourceRef: `subject:youmd/${slug}/overrides`,
+                sourceRevision: `sha256:${(0, canonical_1.sha256)(source.content)}`,
+                path: source.sourcePath,
+            },
+        }));
+    }
+    proposals.sort((a, b) => a.proposalRef.localeCompare(b.proposalRef));
+    errors.sort((a, b) => a.sourcePath.localeCompare(b.sourcePath) || a.code.localeCompare(b.code));
+    return { proposals, errors };
+}
+//# sourceMappingURL=proposal.js.map