@sema-ai/core 1.275.1

package/dist/core/memory-engine/scope-contract.d.ts

@@ -0,0 +1,104 @@
+/** Per-segment cap, measured AFTER encoding. A conservative portability policy adopted as contract
+ *  (research (d) recommendation — NOT a verified third-party hard limit; uuidv7 = 36 chars fits). */
+export declare const SCOPE_SEGMENT_MAX_ENCODED = 64;
+/**
+ * Canonical injective encoding for a raw identifier entering a scope key: everything outside
+ * `[A-Za-z0-9._-]` becomes `%XX` (UTF-8 bytes), INCLUDING `%` itself (that self-encoding is what
+ * makes the map injective — no `__`-style collidable escapes). Throws when the encoded segment
+ * exceeds {@link SCOPE_SEGMENT_MAX_ENCODED} (an over-long principal is a deployment config error)
+ * or when the raw value is empty.
+ */
+export declare function encodeScopeSegment(raw: string): string;
+/**
+ * Inverse of {@link encodeScopeSegment}, CANONICAL-FORM ONLY (codex 复审 B6): the input must be
+ * exactly what the encoder produces — safe chars stay bare (so `%41` for `A` is refused: two
+ * spellings of one identity must not mint two keys), `%XX` sequences must decode as valid UTF-8
+ * (fatal decoder — no U+FFFD smoothing), and the 64-char cap holds here too (parse side enforces
+ * what the format side promised).
+ */
+export declare function decodeScopeSegment(encoded: string): string;
+export type ParsedScopeKey = {
+    kind: "user";
+    principal: string;
+} | {
+    kind: "org";
+    tenant: string;
+} | {
+    kind: "proj";
+    tenant: string;
+    projectId: string;
+} | {
+    kind: "userproj";
+    principal: string;
+    projectId: string;
+}
+/** No recognized v2 prefix: an opaque legacy scope (fully valid under the v2 contract too). */
+ | {
+    kind: "legacy";
+    raw: string;
+};
+export declare function formatUserScope(principal: string): string;
+export declare function formatOrgScope(tenant: string): string;
+export declare function formatProjScope(tenant: string, projectId: string): string;
+export declare function formatUserProjScope(principal: string, projectId: string): string;
+/**
+ * Parse a scope key under the v2 contract. A key carrying a recognized prefix MUST be well-formed
+ * (fail-loud — a malformed `proj:` key under an explicit opt-in is a config error, not an opaque
+ * scope); anything without a recognized prefix parses as `{ kind: "legacy" }` and keeps today's
+ * opaque behavior. NEVER call this on a deployment that has not opted in (see module header).
+ */
+export declare function parseScopeKey(key: string): ParsedScopeKey;
+/** True when a v2-parsed key belongs to a PERSONAL plane (`user:` / `userproj:`). */
+export declare function isPersonalScope(parsed: ParsedScopeKey): boolean;
+/** True when the key's AUTHORITY is central (design/142 §2 表: user/userproj/org rows) — these keys
+ *  must never project into an in-repo memory dir (they would leak to every collaborator AND enter
+ *  commit history; codex 复审 B1 extended the F9 gate from personal to org). `proj:`/legacy stay
+ *  repo-planed. */
+export declare function isCentralAuthorityScope(parsed: ParsedScopeKey): boolean;
+/**
+ * design/142 §7 S1 hard gate (复审 F9): until S1b per-scope physical roots land, ALL scopes of a
+ * session materialize under ONE root — so a v2 session mixing `user:*`/`userproj:*` keys with an
+ * IN-REPO memory dir would project personal memory into the repo (the exact §2.7 leak shape:
+ * personal notes committed to a shared/open repo). Fail-loud, never fail-open: this throws a
+ * `config.`-coded error the prepare path must NOT swallow.
+ */
+export declare function assertScopeContractPlacement(args: {
+    parsedScopes: readonly ParsedScopeKey[];
+    memoryDir: string;
+    /** The repo/workspace root the session works in (undefined = no repo context, gate passes). */
+    repoRoot: string | undefined;
+}): void;
+/** Repo-root marker file: minted once (by scaffold/deployment, NEVER by the engine), committed, and
+ *  from then on the project's identity survives clone/copy/rename/machine/cloud-sandbox. */
+export declare const PROJECT_MARKER_PATH = ".sema/project";
+/** projectId 格式单源([637]① 承诺):generic UUID,version nibble 不收紧——宽读严写(读面认外部/
+ *  历史 v4;铸造面 formatProjectMarker / center mint 统一产 uuidv7)。center 侧自持镜像+dev-only
+ *  drift 锁对着这条(registry-core coreTypes 先例)。 */
+export declare const PROJECT_ID_REGEX: RegExp;
+/** Serialize a marker file body (scaffold-side helper; the engine itself never writes one). */
+export declare function formatProjectMarker(projectId: string): string;
+/** Parse a marker body: TOML-subset `key = value` lines, `#` comments and blank lines ignored,
+ *  optional quotes around the value. Unknown keys are ignored (forward-compatible). codex 复审 H7:
+ *  ANY line that starts a `projectId` assignment but is not one canonical UUID assignment is a
+ *  CORRUPT marker (fail-loud, `config.memory_project_marker`) — an empty value, an unclosed quote,
+ *  a non-UUID, or a DUPLICATE projectId line must never degrade to "no marker" (that would be a
+ *  silent identity change back to the path key). Returns null only when NO projectId line exists. */
+export declare function parseProjectMarker(body: string): {
+    projectId: string;
+} | null;
+/**
+ * design/142 §1.1 — resolve a project's identity. READS ONLY THE MARKER (复审 F2: never derives an
+ * identity from a git remote; remote-URL normalization is a scaffold-side minting heuristic, not an
+ * identity source). v1 scope (复审 F10): ONE marker at the project root —
+ *  - inside a git repo, the root is the REPO root; a marker at a nested directory that is not the
+ *    repo root is fail-loud (`config.memory_project_marker_nested`) — monorepo sub-project identity
+ *    is a future need-signal, not a silent second identity;
+ *  - outside git, the given rootDir IS the project root (path-form local projects).
+ * Returns null when no marker exists (callers fall through the resolution ladder: explicit
+ * declaration → path fallback with a warning).
+ */
+export declare function resolveProjectId(rootDir: string): {
+    projectId: string;
+    markerDir: string;
+} | null;
+//# sourceMappingURL=scope-contract.d.ts.map

package/dist/core/memory-engine/scope-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-contract.d.ts","sourceRoot":"","sources":["../../../src/core/memory-engine/scope-contract.ts"],"names":[],"mappings":"AAmBA;qGACqG;AACrG,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAI5C;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAmBtD;AAmBD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CA4B1D;AAMD,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE;AAC5D,+FAA+F;GAC7F;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpC,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEzD;AACD,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAErD;AACD,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAEzE;AACD,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAEhF;AAKD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAuBzD;AAED,qFAAqF;AACrF,wBAAgB,eAAe,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAE/D;AAED;;;mBAGmB;AACnB,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAEvE;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE;IACjD,YAAY,EAAE,SAAS,cAAc,EAAE,CAAC;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,+FAA+F;IAC/F,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;CAC9B,GAAG,IAAI,CAiBP;AAMD;4FAC4F;AAC5F,eAAO,MAAM,mBAAmB,kBAAkB,CAAC;AAEnD;;+CAE+C;AAC/C,eAAO,MAAM,gBAAgB,QAAoE,CAAC;AAGlG,+FAA+F;AAC/F,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAG7D;AAED;;;;;qGAKqG;AACrG,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAoB7E;AAYD;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CA4BjG"}

package/dist/core/memory-engine/scope-contract.js

@@ -0,0 +1,288 @@
+// design/142 §1 — the memory scope IDENTITY CONTRACT (r2, clay-approved 2026-07-12).
+//
+// Today `TaskSpec.memory.scopes` are OPAQUE free-form strings; grouping correctness rides entirely on
+// whoever mints them (path-derived keys break on rename / second checkout / every cloud clone). This
+// module is the v2 contract: a typed key syntax (`user:` / `org:` / `proj:` / `userproj:`), an
+// injective segment encoding, and the in-repo project marker that makes a project's identity travel
+// WITH its files instead of living in a path.
+//
+// ACTIVATION IS AN EXPLICIT OPT-IN (`TaskSpec.memory.scopeContract: "v2"`) — never prefix sniffing:
+// `user:42` is the documented LEGACY example shape (types.ts TaskSpec.memory), so recognizing keys by
+// prefix would silently capture existing deployments (design/142 复审 F1, codex+fable double-confirmed
+// BLOCKER). Without the opt-in every scope stays byte-identically opaque.
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+// ---------------------------------------------------------------------------------------------
+// Segment encoding (§1.2) — injective, third-party-portable
+// ---------------------------------------------------------------------------------------------
+/** Per-segment cap, measured AFTER encoding. A conservative portability policy adopted as contract
+ *  (research (d) recommendation — NOT a verified third-party hard limit; uuidv7 = 36 chars fits). */
+export const SCOPE_SEGMENT_MAX_ENCODED = 64;
+const SEGMENT_SAFE = /^[A-Za-z0-9._-]$/;
+/**
+ * Canonical injective encoding for a raw identifier entering a scope key: everything outside
+ * `[A-Za-z0-9._-]` becomes `%XX` (UTF-8 bytes), INCLUDING `%` itself (that self-encoding is what
+ * makes the map injective — no `__`-style collidable escapes). Throws when the encoded segment
+ * exceeds {@link SCOPE_SEGMENT_MAX_ENCODED} (an over-long principal is a deployment config error)
+ * or when the raw value is empty.
+ */
+export function encodeScopeSegment(raw) {
+    if (raw.length === 0)
+        throw new Error("scope segment must be non-empty");
+    // codex 复审 B6: a lone surrogate would silently become U+FFFD in UTF-8 (two distinct JS strings
+    // → one key = injectivity broken). Refuse non-well-formed input outright.
+    if (!isWellFormedString(raw))
+        throw new Error("scope segment is not well-formed Unicode (lone surrogate)");
+    let out = "";
+    for (const ch of raw) {
+        if (SEGMENT_SAFE.test(ch)) {
+            out += ch;
+        }
+        else {
+            for (const byte of Buffer.from(ch, "utf8"))
+                out += `%${byte.toString(16).toUpperCase().padStart(2, "0")}`;
+        }
+    }
+    if (out.length > SCOPE_SEGMENT_MAX_ENCODED) {
+        throw new Error(`scope segment exceeds ${SCOPE_SEGMENT_MAX_ENCODED} encoded chars (${out.length}): ${out.slice(0, 24)}…`);
+    }
+    return out;
+}
+function isWellFormedString(s) {
+    // String.prototype.isWellFormed (Node ≥20) with a manual fallback.
+    const anyS = s;
+    if (typeof anyS.isWellFormed === "function")
+        return anyS.isWellFormed();
+    for (let i = 0; i < s.length; i++) {
+        const c = s.charCodeAt(i);
+        if (c >= 0xd800 && c <= 0xdbff) {
+            const n = s.charCodeAt(i + 1);
+            if (!(n >= 0xdc00 && n <= 0xdfff))
+                return false;
+            i++;
+        }
+        else if (c >= 0xdc00 && c <= 0xdfff)
+            return false;
+    }
+    return true;
+}
+const FATAL_UTF8 = new TextDecoder("utf-8", { fatal: true });
+/**
+ * Inverse of {@link encodeScopeSegment}, CANONICAL-FORM ONLY (codex 复审 B6): the input must be
+ * exactly what the encoder produces — safe chars stay bare (so `%41` for `A` is refused: two
+ * spellings of one identity must not mint two keys), `%XX` sequences must decode as valid UTF-8
+ * (fatal decoder — no U+FFFD smoothing), and the 64-char cap holds here too (parse side enforces
+ * what the format side promised).
+ */
+export function decodeScopeSegment(encoded) {
+    if (encoded.length > SCOPE_SEGMENT_MAX_ENCODED) {
+        throw new Error(`scope segment exceeds ${SCOPE_SEGMENT_MAX_ENCODED} encoded chars (${encoded.length})`);
+    }
+    if (!/^(?:[A-Za-z0-9._-]|%[0-9A-F]{2})*$/.test(encoded)) {
+        throw new Error(`malformed scope segment: ${encoded}`);
+    }
+    const bytes = [];
+    for (let i = 0; i < encoded.length; i++) {
+        if (encoded[i] === "%") {
+            bytes.push(parseInt(encoded.slice(i + 1, i + 3), 16));
+            i += 2;
+        }
+        else {
+            bytes.push(encoded.charCodeAt(i));
+        }
+    }
+    let decoded;
+    try {
+        decoded = FATAL_UTF8.decode(Uint8Array.from(bytes));
+    }
+    catch {
+        throw new Error(`malformed scope segment (invalid UTF-8 in %XX sequence): ${encoded}`);
+    }
+    // Canonical-form check: re-encoding must reproduce the input byte-for-byte. This rejects
+    // non-canonical spellings (`%41` for `A`) in ONE rule instead of case-by-case validation.
+    if (encodeScopeSegment(decoded) !== encoded) {
+        throw new Error(`non-canonical scope segment (re-encode mismatch): ${encoded}`);
+    }
+    return decoded;
+}
+export function formatUserScope(principal) {
+    return `user:${encodeScopeSegment(principal)}`;
+}
+export function formatOrgScope(tenant) {
+    return `org:${encodeScopeSegment(tenant)}`;
+}
+export function formatProjScope(tenant, projectId) {
+    return `proj:${encodeScopeSegment(tenant)}/${encodeScopeSegment(projectId)}`;
+}
+export function formatUserProjScope(principal, projectId) {
+    return `userproj:${encodeScopeSegment(principal)}/${encodeScopeSegment(projectId)}`;
+}
+const ONE_SEGMENT = /^(user|org):((?:[A-Za-z0-9._-]|%[0-9A-F]{2})+)$/;
+const TWO_SEGMENT = /^(proj|userproj):((?:[A-Za-z0-9._-]|%[0-9A-F]{2})+)\/((?:[A-Za-z0-9._-]|%[0-9A-F]{2})+)$/;
+/**
+ * Parse a scope key under the v2 contract. A key carrying a recognized prefix MUST be well-formed
+ * (fail-loud — a malformed `proj:` key under an explicit opt-in is a config error, not an opaque
+ * scope); anything without a recognized prefix parses as `{ kind: "legacy" }` and keeps today's
+ * opaque behavior. NEVER call this on a deployment that has not opted in (see module header).
+ */
+export function parseScopeKey(key) {
+    const m1 = ONE_SEGMENT.exec(key);
+    if (m1) {
+        const seg = decodeScopeSegment(m1[2]);
+        return m1[1] === "user" ? { kind: "user", principal: seg } : { kind: "org", tenant: seg };
+    }
+    const m2 = TWO_SEGMENT.exec(key);
+    if (m2) {
+        const a = decodeScopeSegment(m2[2]);
+        const b = decodeScopeSegment(m2[3]);
+        return m2[1] === "proj" ? { kind: "proj", tenant: a, projectId: b } : { kind: "userproj", principal: a, projectId: b };
+    }
+    const prefix = /^(user|org|proj|userproj):/.exec(key);
+    if (prefix) {
+        const e = new Error(`malformed v2 scope key "${key}": prefix "${prefix[1]}:" is reserved by the scope contract ` +
+            `(design/142 §1.2) — segments must be encoded with encodeScopeSegment (charset [A-Za-z0-9._-] + %XX), ` +
+            `"${prefix[1]}" takes ${prefix[1] === "proj" || prefix[1] === "userproj" ? "two segments (a/b)" : "one segment"}.`);
+        e.code = "config.memory_scope_key";
+        throw e;
+    }
+    return { kind: "legacy", raw: key };
+}
+/** True when a v2-parsed key belongs to a PERSONAL plane (`user:` / `userproj:`). */
+export function isPersonalScope(parsed) {
+    return parsed.kind === "user" || parsed.kind === "userproj";
+}
+/** True when the key's AUTHORITY is central (design/142 §2 表: user/userproj/org rows) — these keys
+ *  must never project into an in-repo memory dir (they would leak to every collaborator AND enter
+ *  commit history; codex 复审 B1 extended the F9 gate from personal to org). `proj:`/legacy stay
+ *  repo-planed. */
+export function isCentralAuthorityScope(parsed) {
+    return isPersonalScope(parsed) || parsed.kind === "org";
+}
+/**
+ * design/142 §7 S1 hard gate (复审 F9): until S1b per-scope physical roots land, ALL scopes of a
+ * session materialize under ONE root — so a v2 session mixing `user:*`/`userproj:*` keys with an
+ * IN-REPO memory dir would project personal memory into the repo (the exact §2.7 leak shape:
+ * personal notes committed to a shared/open repo). Fail-loud, never fail-open: this throws a
+ * `config.`-coded error the prepare path must NOT swallow.
+ */
+export function assertScopeContractPlacement(args) {
+    if (!args.repoRoot)
+        return;
+    const personal = args.parsedScopes.filter(isCentralAuthorityScope);
+    if (personal.length === 0)
+        return;
+    const root = resolve(args.repoRoot);
+    const dir = resolve(args.memoryDir);
+    if (dir === root || dir.startsWith(root + "/")) {
+        const e = new Error(`memory scope contract v2: central-authority scope(s) ${personal
+            .map((p) => `"${p.kind}"`)
+            .join(", ")} cannot materialize into an IN-REPO memory dir (${args.memoryDir}) — ` +
+            `a user/userproj/org layer projected under the repo root would leak non-repo memory to every ` +
+            `collaborator (and into commit history). Move the memory dir out of the repo, or drop those scopes.`);
+        e.code = "config.memory_scope_placement";
+        throw e;
+    }
+}
+// ---------------------------------------------------------------------------------------------
+// Project marker (§1.1) — identity travels with the files
+// ---------------------------------------------------------------------------------------------
+/** Repo-root marker file: minted once (by scaffold/deployment, NEVER by the engine), committed, and
+ *  from then on the project's identity survives clone/copy/rename/machine/cloud-sandbox. */
+export const PROJECT_MARKER_PATH = ".sema/project";
+/** projectId 格式单源([637]① 承诺):generic UUID,version nibble 不收紧——宽读严写(读面认外部/
+ *  历史 v4;铸造面 formatProjectMarker / center mint 统一产 uuidv7)。center 侧自持镜像+dev-only
+ *  drift 锁对着这条(registry-core coreTypes 先例)。 */
+export const PROJECT_ID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const UUID_RE = PROJECT_ID_REGEX;
+/** Serialize a marker file body (scaffold-side helper; the engine itself never writes one). */
+export function formatProjectMarker(projectId) {
+    if (!UUID_RE.test(projectId))
+        throw new Error(`projectId must be a UUID, got: ${projectId}`);
+    return `projectId = ${projectId.toLowerCase()}\n`;
+}
+/** Parse a marker body: TOML-subset `key = value` lines, `#` comments and blank lines ignored,
+ *  optional quotes around the value. Unknown keys are ignored (forward-compatible). codex 复审 H7:
+ *  ANY line that starts a `projectId` assignment but is not one canonical UUID assignment is a
+ *  CORRUPT marker (fail-loud, `config.memory_project_marker`) — an empty value, an unclosed quote,
+ *  a non-UUID, or a DUPLICATE projectId line must never degrade to "no marker" (that would be a
+ *  silent identity change back to the path key). Returns null only when NO projectId line exists. */
+export function parseProjectMarker(body) {
+    const corrupt = (detail) => {
+        const e = new Error(`corrupt project marker: ${detail}`);
+        e.code = "config.memory_project_marker";
+        throw e;
+    };
+    let projectId;
+    for (const line of body.split(/\r?\n/)) {
+        const t = line.trim();
+        if (!t || t.startsWith("#"))
+            continue;
+        if (!/^projectId\b/.test(t))
+            continue;
+        const m = /^projectId\s*=\s*(?:"([^"]*)"|([^"\s]+))\s*$/.exec(t);
+        if (!m)
+            corrupt(`unparseable projectId line (${t.slice(0, 48)})`);
+        const value = m[1] ?? m[2] ?? "";
+        if (!UUID_RE.test(value))
+            corrupt(`projectId is not a UUID (${value.slice(0, 48) || "<empty>"})`);
+        if (projectId !== undefined && projectId !== value.toLowerCase())
+            corrupt("duplicate conflicting projectId lines");
+        projectId = value.toLowerCase();
+    }
+    if (projectId === undefined)
+        return null;
+    return { projectId };
+}
+function gitRootOf(dir) {
+    let cur = resolve(dir);
+    for (;;) {
+        if (existsSync(join(cur, ".git")))
+            return cur;
+        const parent = dirname(cur);
+        if (parent === cur)
+            return undefined;
+        cur = parent;
+    }
+}
+/**
+ * design/142 §1.1 — resolve a project's identity. READS ONLY THE MARKER (复审 F2: never derives an
+ * identity from a git remote; remote-URL normalization is a scaffold-side minting heuristic, not an
+ * identity source). v1 scope (复审 F10): ONE marker at the project root —
+ *  - inside a git repo, the root is the REPO root; a marker at a nested directory that is not the
+ *    repo root is fail-loud (`config.memory_project_marker_nested`) — monorepo sub-project identity
+ *    is a future need-signal, not a silent second identity;
+ *  - outside git, the given rootDir IS the project root (path-form local projects).
+ * Returns null when no marker exists (callers fall through the resolution ladder: explicit
+ * declaration → path fallback with a warning).
+ */
+export function resolveProjectId(rootDir) {
+    const dir = resolve(rootDir);
+    const gitRoot = gitRootOf(dir);
+    const projectRoot = gitRoot ?? dir;
+    // codex 复审 M13: scan EVERY level from the call dir up to the repo root — a nested marker at an
+    // intermediate directory (repo/sub/.sema/project when called from repo/sub/deeper) is the same
+    // v1 violation as one at the call dir itself; missing it would silently split identities.
+    if (gitRoot !== undefined) {
+        let cur = dir;
+        while (cur !== gitRoot) {
+            if (existsSync(join(cur, PROJECT_MARKER_PATH))) {
+                const e = new Error(`nested project marker: ${join(cur, PROJECT_MARKER_PATH)} sits below the repo root (${gitRoot}) — ` +
+                    `v1 supports ONE marker at the repo root (design/142 §1.1); remove the nested marker or split the repo.`);
+                e.code = "config.memory_project_marker_nested";
+                throw e;
+            }
+            const parent = dirname(cur);
+            if (parent === cur)
+                break;
+            cur = parent;
+        }
+    }
+    const markerFile = join(projectRoot, PROJECT_MARKER_PATH);
+    if (!existsSync(markerFile))
+        return null;
+    const parsed = parseProjectMarker(readFileSync(markerFile, "utf8"));
+    if (!parsed)
+        return null;
+    return { projectId: parsed.projectId, markerDir: projectRoot };
+}
+//# sourceMappingURL=scope-contract.js.map

package/dist/core/memory-engine/scope-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-contract.js","sourceRoot":"","sources":["../../../src/core/memory-engine/scope-contract.ts"],"names":[],"mappings":"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"}

package/dist/core/memory-engine/sync-client.d.ts

@@ -0,0 +1,100 @@
+import { type MemorySyncCursor } from "./sync.js";
+import type { MemoryBackend, MemoryEntry, PatchReport } from "./types.js";
+/** The injected HTTP seam — core never bundles a fetch. The deployment maps `path` (e.g.
+ *  `/v1/memory/sync/user%3Aalice`) onto its server base URL, attaches auth, and returns the
+ *  DECODED JSON body of a 2xx response; any non-2xx / network failure should THROW (the round then
+ *  aborts with zero local side effects — the transport runs before any local write). */
+export type MemorySyncTransport = (path: string, body: unknown) => Promise<unknown>;
+/** The wire REQUEST of one round (the server's `parseMemorySyncRequest` twin — [671]①): the push
+ *  half as computed against the client's own cursor. `deletes` ⊆ `Object.keys(baseRevs)` by
+ *  construction (a delete is CAS'd on its baseline; an id never synced cannot be delete-propagated). */
+export interface MemorySyncRequestBody {
+    peer: string;
+    /** id → rev at the last completed round (the cursor's baseRevs; empty = first round). */
+    baseRevs: Record<string, string>;
+    /** Full state of every entry new/changed here since the baseline. */
+    entries: MemoryEntry[];
+    /** Ids deleted here since the baseline (tombstoned or gone from the local plane). */
+    deletes: string[];
+}
+/** The wire RESPONSE of one round (server `MemorySyncResponse` twin — [671]①: one RTT, both
+ *  directions; `serverDeletes` is the delete-propagation leg [codex B4 — without it a central
+ *  removal never crosses = livelock]; `cursor` is the server-computed next baseline with the
+ *  retention discipline ALREADY applied to the pull half). */
+export interface MemorySyncResponseBody {
+    /** Ops the server actually landed from our push (empty on an idempotent replay). */
+    applied: PatchReport["applied"];
+    /** Server-side rejections/divergences: inbound-gate rejects, rev lies, CAS losses, both-sides
+     *  divergence (resolve via the §3 ladder — loser minted as a sibling, never dropped). */
+    conflicts: Array<{
+        id: string;
+        reason: string;
+        baseRev?: string;
+        currentRev?: string;
+    }>;
+    /** The pull half: entries new/changed centrally since our baseline. */
+    serverEntries: MemoryEntry[];
+    /** The pull half's delete leg: centrally deleted, unchanged here since baseline (CAS baseRev). */
+    serverDeletes: Array<{
+        id: string;
+        baseRev: string;
+    }>;
+    /** The next baseline to persist AFTER the pull half lands (the client cannot compute it — it
+     *  does not hold the central set). Pull-half ids are retained at the OLD baseline inside. */
+    cursor: {
+        peer: string;
+        baseRevs: Record<string, string>;
+        updatedAtMs: number;
+    };
+}
+/** One aggregated conflict: `server` = reported by the central half (its gate/CAS/divergence),
+ *  `local` = produced landing the pull half here (our CAS refusals, inbound-gate rejects, rev
+ *  lies). Nothing is hidden; the caller resolves via the §3 ladder (loser-as-sibling). */
+export interface MemorySyncClientConflict {
+    side: "server" | "local";
+    id: string;
+    reason: string;
+    baseRev?: string;
+    currentRev?: string;
+}
+export interface SyncMemoryScopeOptions {
+    /** The LOCAL authority plane (TOC: the File backend). */
+    backend: MemoryBackend;
+    /** The scope this round syncs (one round = one scope, mirroring the server route). */
+    scope: string;
+    /** The injected HTTP seam. */
+    transport: MemorySyncTransport;
+    /** The persisted cursor from the last completed round with this peer; absent = first round. */
+    cursor?: MemorySyncCursor;
+    /** Peer name for the cursor partition (defaults to the cursor's peer, else "central"). */
+    peer?: string;
+    /** Caller-injected clock (engine precedent) — stamps the returned cursor's updatedAtMs. */
+    now?: () => number;
+}
+export interface MemorySyncClientResult {
+    /** True ⇔ the round was fully clean: cursor advanced AND zero conflicts on either side. */
+    ok: boolean;
+    /** What the push half contained (ids only — the bodies already went over the wire). */
+    pushed: {
+        entries: string[];
+        deletes: string[];
+    };
+    /** Ops the server landed from our push (response `applied` verbatim). */
+    serverApplied: PatchReport["applied"];
+    /** Ops we landed locally from the pull half. */
+    localApplied: PatchReport["applied"];
+    /** Aggregated server-reported + local conflicts (never hidden). */
+    conflicts: MemorySyncClientConflict[];
+    /** True ⇔ every pull-half item landed cleanly, so `cursor` is the NEW baseline to persist. */
+    cursorAdvanced: boolean;
+    /** The cursor the caller should now persist: advanced on full success, otherwise the INPUT
+     *  cursor unchanged (undefined on a failed first round) — the retention discipline. */
+    cursor: MemorySyncCursor | undefined;
+}
+/**
+ * One full CLIENT sync round for one (scope, peer) against the [671]① central sync API — see the
+ * module header for the ①-⑤ flow and the cursor retention discipline. Pure orchestration: all I/O
+ * rides the injected backend/transport; the caller persists the returned cursor.
+ */
+export declare function syncMemoryScope(opts: SyncMemoryScopeOptions): Promise<MemorySyncClientResult>;
+//# sourceMappingURL=sync-client.d.ts.map

package/dist/core/memory-engine/sync-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-client.d.ts","sourceRoot":"","sources":["../../../src/core/memory-engine/sync-client.ts"],"names":[],"mappings":"AAoCA,OAAO,EAA0B,KAAK,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC1E,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAa,WAAW,EAAE,MAAM,YAAY,CAAC;AAErF;;;wFAGwF;AACxF,MAAM,MAAM,mBAAmB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAEpF;;wGAEwG;AACxG,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,yFAAyF;IACzF,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,qEAAqE;IACrE,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,qFAAqF;IACrF,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;8DAG8D;AAC9D,MAAM,WAAW,sBAAsB;IACrC,oFAAoF;IACpF,OAAO,EAAE,WAAW,CAAC,SAAS,CAAC,CAAC;IAChC;6FACyF;IACzF,SAAS,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACxF,uEAAuE;IACvE,aAAa,EAAE,WAAW,EAAE,CAAC;IAC7B,kGAAkG;IAClG,aAAa,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACtD;iGAC6F;IAC7F,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;CACjF;AAED;;0FAE0F;AAC1F,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,sBAAsB;IACrC,yDAAyD;IACzD,OAAO,EAAE,aAAa,CAAC;IACvB,sFAAsF;IACtF,KAAK,EAAE,MAAM,CAAC;IACd,8BAA8B;IAC9B,SAAS,EAAE,mBAAmB,CAAC;IAC/B,+FAA+F;IAC/F,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,0FAA0F;IAC1F,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2FAA2F;IAC3F,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,sBAAsB;IACrC,2FAA2F;IAC3F,EAAE,EAAE,OAAO,CAAC;IACZ,uFAAuF;IACvF,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,EAAE,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IACjD,yEAAyE;IACzE,aAAa,EAAE,WAAW,CAAC,SAAS,CAAC,CAAC;IACtC,gDAAgD;IAChD,YAAY,EAAE,WAAW,CAAC,SAAS,CAAC,CAAC;IACrC,mEAAmE;IACnE,SAAS,EAAE,wBAAwB,EAAE,CAAC;IACtC,8FAA8F;IAC9F,cAAc,EAAE,OAAO,CAAC;IACxB;2FACuF;IACvF,MAAM,EAAE,gBAAgB,GAAG,SAAS,CAAC;CACtC;AA0GD;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,sBAAsB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CA2KnG"}