@hyperframes/share 0.9.28-alpha.0 → 0.9.28

package/src/sources/contract.mjs

@@ -1,13 +0,0 @@
-// @ts-check
-// Load the bundled snapshot policy and Unicode registries from JSON or Brotli.
-import { existsSync, readFileSync } from "node:fs";
-import { brotliDecompressSync } from "node:zlib";
-
-/** A registry's parsed JSON. @param {string} name a file in contract/, such as "path-policy.json" @returns {any} */
-export function readContract(name) {
-  const packed = new URL(`./contract/${name}.br`, import.meta.url);
-  const text = existsSync(packed)
-    ? brotliDecompressSync(readFileSync(packed)).toString("utf8")
-    : readFileSync(new URL(`./contract/${name}`, import.meta.url), "utf8");
-  return JSON.parse(text);
-}

package/src/sources/errors.mjs

@@ -1,77 +0,0 @@
-// @ts-check
-// Map sync API error codes to stable client error kinds.
-
-/** @typedef {import("./types.js").SyncErrorKind} SyncErrorKind */
-
-/** @type {Record<string, SyncErrorKind>} */
-const KIND_BY_CODE = {
-  hyperframes_composition_sync_not_enabled: "not-enabled",
-  hf_subscription_required: "plan-required",
-  hyperframes_composition_sync_limit_reached: "limit-reached",
-  byok_not_supported: "byok",
-  resource_access_denied: "no-write-role",
-  forbidden: "forbidden",
-  hyperframes_composition_not_found: "composition-not-found",
-  resource_not_found: "not-found",
-  hyperframes_composition_upload_too_large: "too-large",
-  hyperframes_composition_upload_reference_invalid: "reference-invalid",
-  hyperframes_composition_upload_not_pending: "upload-not-pending",
-  hyperframes_composition_active_uploads_exceeded: "active-uploads-exceeded",
-  hyperframes_composition_upload_file_not_writable: "file-not-writable",
-  conflict: "idempotency-key-reused",
-  request_in_progress: "request-in-progress",
-  hyperframes_composition_snapshot_not_downloadable: "snapshot-not-downloadable",
-  hyperframes_composition_conflict_not_open: "conflict-not-open",
-  hyperframes_composition_download_expired: "download-expired",
-  invalid_parameter: "invalid-parameter",
-  rate_limit_exceeded: "rate-limited",
-  service_unavailable: "unavailable",
-};
-
-/** A sync route's refusal or failure. `status` is 0 when the server was never reached. */
-export class SyncApiError extends Error {
-  /** @param {SyncErrorKind} kind @param {{ status?: number, code?: string | null, param?: string | null,
-   *   requestId?: string | null, retryAfterMs?: number | null, detail?: string }} [about] */
-  constructor(kind, about = {}) {
-    super(`composition sync: ${kind}${about.code ? ` (${about.code})` : ""}`);
-    this.name = "SyncApiError";
-    this.kind = kind;
-    this.status = about.status ?? 0;
-    this.code = about.code ?? null;
-    this.param = about.param ?? null;
-    this.requestId = about.requestId ?? null;
-    this.retryAfterMs = about.retryAfterMs ?? null;
-    this.detail = about.detail ?? null;
-  }
-}
-
-/** The kind for an HTTP status whose code this client does not know. @param {number} status
- * @returns {SyncErrorKind} */
-function kindOfStatus(status) {
-  if (status === 404) return "not-found";
-  if (status === 429) return "rate-limited";
-  if (status === 503) return "unavailable";
-  if (status >= 500) return "server-error";
-  return "refused";
-}
-
-/** The typed error for a refusal: the envelope's code when it is one of the sync routes', else the status's.
- * @param {Response} reply @returns {Promise<SyncApiError>} */
-export async function refusalOf(reply) {
-  const payload = await reply.json().catch(() => null);
-  /** @type {{ code?: unknown, param?: unknown, request_id?: unknown, message?: unknown } | undefined} */
-  const error = payload?.error;
-  const code = typeof error?.code === "string" ? error.code : null;
-  const seconds = Number(reply.headers.get("retry-after") ?? Number.NaN);
-  return new SyncApiError((code && KIND_BY_CODE[code]) || kindOfStatus(reply.status), {
-    status: reply.status,
-    code,
-    param: typeof error?.param === "string" ? error.param : null,
-    requestId:
-      typeof error?.request_id === "string"
-        ? error.request_id
-        : reply.headers.get("x-heygen-request-id"),
-    retryAfterMs: seconds >= 0 ? seconds * 1000 : null,
-    ...(typeof error?.message === "string" ? { detail: error.message } : {}),
-  });
-}

package/src/sources/limits.mjs

@@ -1,48 +0,0 @@
-// @ts-check
-// Check the workspace upload limits before hashing or sending files.
-
-const MIB = 1024 * 1024;
-const GIB = 1024 * MIB;
-
-/** @typedef {import("./types.js").Limits} Limits @typedef {import("./types.js").LimitName} LimitName */
-
-/** @type {Limits} */
-export const V1_LIMITS = Object.freeze({
-  maxFiles: 10_000,
-  maxFileBytes: 5 * GIB,
-  maxProjectBytes: 10 * GIB,
-  maxManifestBytes: 8 * MIB,
-});
-
-/** How many of the biggest files an over-limit answer names. */
-const NAMED = 10;
-
-/** A manifest's file count, largest file, total and canonical size; every listed file counts, reused ones too.
- * @param {readonly { size: number }[]} files @param {number} manifestBytes */
-const measure = (files, manifestBytes) => ({
-  fileCount: files.length,
-  largestFileBytes: files.reduce((most, file) => Math.max(most, file.size), 0),
-  projectBytes: files.reduce((sum, file) => sum + file.size, 0),
-  manifestBytes,
-});
-
-/** The first limit broken, in the server's fixed order (file count, file size, project size, manifest size), with
- * the biggest files first; null when the push fits. @param {readonly { path: string, size: number }[]} files
- * @param {number} manifestBytes @param {Limits} [limits] @returns {import("./types.js").OverLimit | null} */
-export function overLimit(files, manifestBytes, limits = V1_LIMITS) {
-  const size = measure(files, manifestBytes);
-  /** @type {[LimitName, number, number][]} */
-  const checks = [
-    ["file_count", size.fileCount, limits.maxFiles],
-    ["file_size", size.largestFileBytes, limits.maxFileBytes],
-    ["project_size", size.projectBytes, limits.maxProjectBytes],
-    ["manifest_size", size.manifestBytes, limits.maxManifestBytes],
-  ];
-  const broken = checks.find(([, actual, maximum]) => actual > maximum);
-  if (!broken) return null;
-  const biggest = [...files]
-    .sort((a, b) => b.size - a.size || (a.path < b.path ? -1 : 1))
-    .slice(0, NAMED)
-    .map(({ path, size: bytes }) => ({ path, size: bytes }));
-  return { limit: broken[0], actual: broken[1], maximum: broken[2], biggest };
-}

package/src/sources/manifest.mjs

@@ -1,154 +0,0 @@
-// @ts-check
-// Serialize snapshots to canonical UTF-8 bytes so clients and the server compute the same digest.
-import { createHash } from "node:crypto";
-import { PathViolation, checkInventoryPaths, validatePath } from "./pathPolicy.mjs";
-
-const FORMAT_VERSION = 1;
-export const ENTRYPOINT = "index.html";
-const MAX_SAFE_SIZE = Number.MAX_SAFE_INTEGER;
-const SHA256 = /^[0-9a-f]{64}$/;
-
-/** @typedef {import("./types.js").ManifestFile} ManifestFile @typedef {import("./types.js").Violation} Violation
- * @typedef {import("./types.js").ManifestDocument} ManifestDocument @typedef {import("./types.js").Manifest} Manifest */
-
-/** Why a manifest was refused; `code` is the first violation's, in the server's order. */
-export class ManifestInvalid extends Error {
-  /** @param {Violation[]} violations */
-  constructor(violations) {
-    super(violations.map((violation) => violation.code).join(", "));
-    this.name = "ManifestInvalid";
-    this.violations = violations;
-    this.code = violations[0]?.code ?? "invalid_schema";
-  }
-}
-
-/** @param {unknown} value @returns {value is Record<string, unknown>} */
-const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-/** @param {unknown} error @returns {Violation} */
-const violationOf = (error) => {
-  if (!(error instanceof PathViolation)) throw error;
-  return { code: error.code, path: error.path, ...(error.rule ? { rule: error.rule } : {}) };
-};
-
-/** A schema violation for each field `fields` does not name.
- * @param {Record<string, unknown>} value @param {readonly string[]} fields @param {Violation[]} out */
-function unknownFields(value, fields, out) {
-  for (const key of Object.keys(value))
-    if (!fields.includes(key)) out.push({ code: "invalid_schema" });
-}
-
-/** @param {unknown} raw @param {Violation[]} out @param {boolean} stored @returns {ManifestFile | null} */
-function fileOf(raw, out, stored) {
-  if (!isObject(raw)) return (out.push({ code: "invalid_schema" }), null);
-  const before = out.length;
-  const { path, sha256, size } = raw;
-  if (typeof path !== "string") out.push({ code: "invalid_schema" });
-  else {
-    try {
-      validatePath(path, stored);
-    } catch (error) {
-      out.push(violationOf(error));
-    }
-  }
-  checkBlob(sha256, size, out);
-  unknownFields(raw, ["path", "sha256", "size"], out);
-  return out.length === before
-    ? { path: String(path), sha256: String(sha256), size: Number(size) }
-    : null;
-}
-
-/** @param {unknown} sha256 @param {unknown} size @param {Violation[]} out */
-function checkBlob(sha256, size, out) {
-  if (typeof sha256 !== "string") out.push({ code: "invalid_schema" });
-  else if (!SHA256.test(sha256)) out.push({ code: "invalid_sha256" });
-  if (typeof size !== "number" || !Number.isInteger(size)) out.push({ code: "invalid_schema" });
-  else if (size < 0 || size > MAX_SAFE_SIZE) out.push({ code: "invalid_size" });
-}
-
-/** UTF-8 byte order, which is code point order; JavaScript's default sort compares UTF-16 units instead.
- * @param {ManifestFile} a @param {ManifestFile} b */
-const byUtf8 = (a, b) => Buffer.compare(Buffer.from(a.path, "utf8"), Buffer.from(b.path, "utf8"));
-
-/** The files in canonical order, or the inventory's first violation. @param {ManifestFile[]} files
- * @param {Violation[]} out */
-function canonicalInventory(files, out) {
-  const ordered = [...files].sort(byUtf8);
-  /** @type {Map<string, number>} */
-  const sizeByDigest = new Map();
-  for (const file of ordered) {
-    const size = sizeByDigest.get(file.sha256) ?? file.size;
-    sizeByDigest.set(file.sha256, size);
-    if (size !== file.size)
-      return (out.push({ code: "inconsistent_digest_size", path: file.path }), null);
-  }
-  try {
-    checkInventoryPaths(ordered.map((file) => file.path));
-  } catch (error) {
-    return (out.push(violationOf(error)), null);
-  }
-  return ordered;
-}
-
-/** @param {unknown} raw @param {Violation[]} out @param {boolean} stored */
-function filesOf(raw, out, stored) {
-  if (!Array.isArray(raw)) return (out.push({ code: "invalid_schema" }), null);
-  const before = out.length;
-  const files = raw.map((item) => fileOf(item, out, stored));
-  if (out.length !== before) return null;
-  return canonicalInventory(/** @type {ManifestFile[]} */ (files), out);
-}
-
-/** The canonical bytes of a valid document. @param {ManifestDocument} document */
-export function canonicalBytes(document) {
-  const files = document.files
-    .map(
-      ({ path, sha256, size }) =>
-        `{"path":${JSON.stringify(path)},"sha256":${JSON.stringify(sha256)},"size":${size}}`,
-    )
-    .join(",");
-  const text = `{"entrypoint":${JSON.stringify(document.entrypoint)},"files":[${files}],"format_version":${document.format_version}}`;
-  return Buffer.from(text, "utf8");
-}
-
-/** Validates a manifest document as the server does; throws ManifestInvalid. @param {unknown} raw
- * @param {boolean} [stored] @returns {Manifest} */
-export function parseManifest(raw, stored = false) {
-  if (!isObject(raw)) throw new ManifestInvalid([{ code: "invalid_schema" }]);
-  /** @type {Violation[]} */
-  const out = [];
-  const { format_version: version, entrypoint } = raw;
-  if (!("format_version" in raw) || typeof version !== "number" || !Number.isInteger(version))
-    out.push({ code: "invalid_schema" });
-  else if (version !== FORMAT_VERSION) out.push({ code: "unsupported_format_version" });
-  if (typeof entrypoint !== "string") out.push({ code: "invalid_schema" });
-  else if (entrypoint !== ENTRYPOINT) out.push({ code: "invalid_entrypoint" });
-  const files = filesOf(raw.files, out, stored);
-  unknownFields(raw, ["format_version", "entrypoint", "files"], out);
-  if (out.length) throw new ManifestInvalid(out);
-  const ordered = /** @type {ManifestFile[]} */ (files);
-  if (!ordered.some((file) => file.path === ENTRYPOINT))
-    throw new ManifestInvalid([{ code: "entrypoint_not_listed" }]);
-  /** @type {ManifestDocument} */
-  const document = { format_version: FORMAT_VERSION, entrypoint: ENTRYPOINT, files: ordered };
-  const canonical = canonicalBytes(document);
-  return { document, canonical, sha256: createHash("sha256").update(canonical).digest("hex") };
-}
-
-/** Stored manifest bytes, which must already be canonical so their hash is the snapshot's manifest_sha256.
- * @param {Uint8Array} body @returns {Manifest} */
-export function parseCanonicalManifest(body) {
-  let document;
-  try {
-    document = JSON.parse(new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(body));
-  } catch {
-    throw new ManifestInvalid([{ code: "invalid_json" }]);
-  }
-  const manifest = parseManifest(document);
-  if (!manifest.canonical.equals(Buffer.from(body)))
-    throw new ManifestInvalid([{ code: "not_canonical" }]);
-  return manifest;
-}
-
-/** A published snapshot or local base can retain v3 paths; its bytes and digest remain immutable.
- * @param {unknown} raw @returns {Manifest} */
-export const parseStoredManifest = (raw) => parseManifest(raw, true);

package/src/sources/pathPolicy.mjs

@@ -1,197 +0,0 @@
-// @ts-check
-// Validate snapshot paths in the order defined by the bundled portable-source-v4 policy.
-import { readContract } from "./contract.mjs";
-import { UNICODE_VERSION, allAssigned, comparisonKey, nfc } from "./unicode.mjs";
-
-const PATH_POLICY_VERSION = "portable-source-v4";
-
-/** @typedef {import("./types.js").PathRule} PathRule @typedef {import("./types.js").PolicyDocument} PolicyDocument */
-
-/** A path the policy refuses: `code` is the golden vectors' shared vocabulary, `rule` the excluding rule's id. */
-export class PathViolation extends Error {
-  /** @param {string} code @param {string} path @param {string} [rule] */
-  constructor(code, path, rule) {
-    super(`${code}: ${JSON.stringify(path)}${rule ? ` (${rule})` : ""}`);
-    this.name = "PathViolation";
-    this.code = code;
-    this.path = path;
-    this.rule = rule ?? null;
-  }
-}
-
-const ASCII = /^\p{ASCII}*$/u;
-
-/** @param {string} pattern */
-const whole = (pattern) => new RegExp(`^(?:${pattern})$`, "su");
-/** @param {string} text */
-const escaped = (text) => text.replace(/[\\\]^-]/g, "\\$&");
-
-/** @param {PolicyDocument} document */
-function compile(document) {
-  if (document.policy_version !== PATH_POLICY_VERSION)
-    throw new Error(`path policy is ${document.policy_version}, expected ${PATH_POLICY_VERSION}`);
-  if (document.unicode.version !== UNICODE_VERSION)
-    throw new Error(
-      `path policy pins Unicode ${document.unicode.version}, the table is ${UNICODE_VERSION}`,
-    );
-  if (document.rules.at(-1)?.regex !== ".+")
-    throw new Error("path policy must end with a catch-all rule, so every path is classified");
-  for (const rule of document.rules)
-    if ((rule.server_action === "allow") !== (rule.client_action === "include"))
-      throw new Error(`path rule ${rule.id}: the server allows exactly what clients include`);
-  const limits = document.path;
-  return {
-    limits,
-    invalidCharacter: new RegExp(
-      `[\\x00-\\x1f\\x7f-\\x9f\\ud800-\\udfff${escaped(limits.forbidden_characters)}]`,
-      "u",
-    ),
-    reservedSegment: whole(limits.reserved_segment_regex),
-    canonicalRoots: new Map(
-      limits.canonical_spelling_roots.map((root) => [comparisonKey(root), root]),
-    ),
-    rules: document.rules.map((rule) => ({ rule, pattern: whole(rule.regex) })),
-    storedRules: document.rules.map((rule) => ({
-      rule,
-      pattern: whole(
-        rule.id === "agent-client-state"
-          ? document.stored_manifest.legacy_agent_state_regex
-          : rule.regex,
-      ),
-    })),
-    prefilter: new Set(document.client_prefilter.names),
-    symlinkPrefixes: document.client_symlinks.skip_prefixes,
-  };
-}
-
-/** @type {ReturnType<typeof compile> | null} */
-let compiled = null;
-/** The policy, read and compiled when a path is first checked: an app that never syncs never reads it. */
-const policy = () => (compiled ??= compile(readContract("path-policy.json")));
-
-/** Every segment replaced by its comparison key. @param {string} path */
-const foldedPath = (path) => path.split("/").map(comparisonKey).join("/");
-
-/** The first rule matching a path's folded spelling. @param {string} path @returns {PathRule} */
-export function classifyPath(path) {
-  const folded = foldedPath(path);
-  const found = policy().rules.find(({ pattern }) => pattern.test(folded));
-  if (!found) throw new Error("the path policy's catch-all rule did not match");
-  return found.rule;
-}
-
-/** Checks 1 to 10 of the registry's `path.checks`: the ones about the string itself. @param {string} path */
-function checkSpelling(path) {
-  const { limits, invalidCharacter } = policy();
-  if (!path) throw new PathViolation("path_empty", path);
-  if (invalidCharacter.test(path)) throw new PathViolation("path_invalid_character", path);
-  if (!ASCII.test(path) && !allAssigned(path))
-    throw new PathViolation("path_unassigned_code_point", path);
-  if (nfc(path) !== path) throw new PathViolation("path_not_nfc", path);
-  if (Buffer.byteLength(path, "utf8") > limits.max_path_bytes)
-    throw new PathViolation("path_too_long", path);
-  if (path.startsWith("/")) throw new PathViolation("path_not_relative", path);
-  return checkSegments(path, limits);
-}
-/** @param {string} path @param {PolicyDocument["path"]} limits */
-function checkSegments(path, limits) {
-  const segments = path.split("/");
-  if (segments.some((segment) => !segment)) throw new PathViolation("path_empty_segment", path);
-  if (segments.some((segment) => segment === "." || segment === ".."))
-    throw new PathViolation("path_dot_segment", path);
-  if (segments.some((segment) => Buffer.byteLength(segment, "utf8") > limits.max_segment_bytes))
-    throw new PathViolation("segment_too_long", path);
-  if (segments.some((segment) => segment.endsWith(".") || segment.endsWith(" ")))
-    throw new PathViolation("segment_trailing_dot_or_space", path);
-  return segments;
-}
-
-/** `path` unchanged when every client can store it and the policy lets it travel; throws PathViolation otherwise,
- * naming the first failing check in the registry's order. @param {string} path
- * @param {boolean} [stored] */
-export function validatePath(path, stored = false) {
-  const segments = checkSpelling(path);
-  const keys = segments.map(comparisonKey);
-  const { reservedSegment, canonicalRoots } = policy();
-  const rules = stored ? policy().storedRules : policy().rules;
-  if (keys.some((key) => reservedSegment.test(key))) throw new PathViolation("reserved_name", path);
-  const root = canonicalRoots.get(keys[0] ?? "");
-  if (root !== undefined && segments[0] !== root)
-    throw new PathViolation("reserved_path_alias", path);
-  const folded = keys.join("/");
-  const found = rules.find(({ pattern }) => pattern.test(folded));
-  if (!found) throw new Error("the path policy's catch-all rule did not match");
-  if (found.rule.server_action === "reject")
-    throw new PathViolation("excluded_path", path, found.rule.id);
-  if (!found.pattern.test(path))
-    throw new PathViolation("reserved_path_alias", path, found.rule.id);
-  return path;
-}
-
-/** Refuses duplicates, and any two paths (or a path and a directory prefix) one filesystem would store as one name.
- * Each path must already pass validatePath. @param {readonly string[]} paths */
-export function checkInventoryPaths(paths) {
-  const seen = { spellingByKey: new Map(), fileKeys: new Set(), directoryKeys: new Set() };
-  for (const path of paths) {
-    const segments = path.split("/");
-    const keys = segments.map(comparisonKey);
-    for (let depth = 1; depth <= segments.length; depth++)
-      notePrefix(seen, path, {
-        prefix: segments.slice(0, depth).join("/"),
-        key: keys.slice(0, depth).join("/"),
-        isFile: depth === segments.length,
-      });
-  }
-}
-
-/** One prefix of `path`, against every prefix before it, in the server's order of checks.
- * @param {{ spellingByKey: Map<string, string>, fileKeys: Set<string>, directoryKeys: Set<string> }} seen
- * @param {string} path @param {{ prefix: string, key: string, isFile: boolean }} at */
-function notePrefix(seen, path, { prefix, key, isFile }) {
-  const spelling = seen.spellingByKey.get(key) ?? prefix;
-  seen.spellingByKey.set(key, spelling);
-  if (isFile && seen.fileKeys.has(key))
-    throw new PathViolation(spelling === prefix ? "duplicate_path" : "path_collision", path);
-  if (spelling !== prefix) throw new PathViolation("path_collision", path);
-  if (isFile ? seen.directoryKeys.has(key) : seen.fileKeys.has(key))
-    throw new PathViolation("file_directory_collision", path);
-  (isFile ? seen.fileKeys : seen.directoryKeys).add(key);
-}
-
-/** The registry's `client_prefilter`: a name (macOS's `Icon\r`) skipped before any path check. @param {string} name */
-export const prefiltered = (name) => policy().prefilter.has(name);
-
-/** The registry's `client_symlinks`: a link under `assets/podcast/` is skipped instead of failing the capture.
- * @param {string} path */
-export const skippedSymlink = (path) =>
-  policy().symlinkPrefixes.some((prefix) => foldedPath(path).startsWith(prefix));
-
-/** The literal text a rule's regex starts with, up to its first metacharacter. @param {string} regex */
-function literalPrefix(regex) {
-  let text = "";
-  for (let i = 0; i < regex.length; i++) {
-    const char = regex[i] ?? "";
-    if (char === "\\" && /[./-]/.test(regex[i + 1] ?? "")) text += regex[++i];
-    else if (/[\w/-]/.test(char)) text += char;
-    else break;
-  }
-  return text;
-}
-
-/** Whether no file under folder `dir` can be listed, so a capture need not open it: its first matching rule
- * excludes the folder and all below it, and no include rule before that one can reach inside. @param {string} dir */
-export function excludedFolder(dir) {
-  const folded = foldedPath(dir);
-  const at = policy().rules.findIndex(
-    ({ pattern, rule }) =>
-      rule.client_action !== "include" && pattern.test(folded) && pattern.test(`${folded}/x`),
-  );
-  if (at < 0) return false;
-  return policy()
-    .rules.slice(0, at)
-    .every(({ rule }) => {
-      if (rule.client_action !== "include") return true;
-      const prefix = literalPrefix(rule.regex);
-      return !(prefix.startsWith(`${folded}/`) || `${folded}/`.startsWith(prefix));
-    });
-}

package/src/sources/projectState.mjs

@@ -1,59 +0,0 @@
-// @ts-check
-// What the HyperFrames CLI keeps in a project's .hyperframes folder that a capture must honour: render outputs written
-// outside renders/ (left out of every manifest), an open agent turn and a held project lock (no capture until both
-// end). The formats are the pinned hyperframes CLI's, version 1 of render-outputs.json.
-import { readFile } from "node:fs/promises";
-import { join } from "node:path";
-
-/** A predicate for the paths the project's render-outputs.json lists, and everything under them; none when the file
- * is missing or not version 1. @param {string} root @returns {Promise<(rel: string) => boolean>} */
-export async function readRenderOutputs(root) {
-  const raw = await readFile(join(root, ".hyperframes", "render-outputs.json"), "utf8").catch(
-    () => null,
-  );
-  /** @type {{ version?: unknown, paths?: unknown } | null} */
-  let record = null;
-  try {
-    record = raw === null ? null : JSON.parse(raw);
-  } catch {
-    record = null;
-  }
-  const paths =
-    record?.version === 1 && Array.isArray(record.paths)
-      ? record.paths
-          .filter((path) => typeof path === "string")
-          .map((path) => path.replace(/\\/g, "/"))
-      : [];
-  const listed = new Set(paths);
-  return (rel) => listed.has(rel) || paths.some((path) => rel.startsWith(`${path}/`));
-}
-
-/** Whether a pid still runs: EPERM is a process another user owns. @param {number} pid */
-function alive(pid) {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (error) {
-    return /** @type {NodeJS.ErrnoException} */ (error).code === "EPERM";
-  }
-}
-
-/** An open agent turn (its history-turn.json exists) or a project lock whose holder still runs.
- * @param {string} root */
-export async function settledState(root) {
-  const dir = join(root, ".hyperframes");
-  const turn = await readFile(join(dir, "history-turn.json")).then(
-    () => true,
-    () => false,
-  );
-  const lock = await readFile(join(dir, "project.lock"), "utf8").catch(() => null);
-  /** @type {{ pid?: unknown } | null} */
-  let holder = null;
-  try {
-    holder = lock === null ? null : JSON.parse(lock);
-  } catch {
-    holder = null;
-  }
-  const locked = lock !== null && (typeof holder?.pid !== "number" || alive(holder.pid));
-  return { agentTurnOpen: turn, projectLocked: locked };
-}

package/src/sources/store.mjs

@@ -1,82 +0,0 @@
-// @ts-check
-import { createHash } from "node:crypto";
-import { constants } from "node:fs";
-import { lstat, open } from "node:fs/promises";
-import { join } from "node:path";
-import { errorCode, mkdirInside, writeJsonAtomic } from "../storage.mjs";
-import { parseStoredManifest } from "./manifest.mjs";
-
-/** @param {unknown} value @returns {value is Record<string, unknown>} */
-const object = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-/** @param {unknown} raw @param {import("./types.js").BindingKey} key @returns {import("./types.js").Binding} */
-function bindingOf(raw, key) {
-  if (
-    !object(raw) ||
-    raw.version !== 1 ||
-    raw.backend !== key.backend ||
-    raw.account !== key.account ||
-    raw.projectPath !== key.projectPath ||
-    typeof raw.compositionId !== "string" ||
-    typeof raw.ownerSpaceId !== "string"
-  )
-    throw new Error(
-      "Source binding belongs to another account, backend or project. Reset explicitly before sharing this copy.",
-    );
-  checkSnapshots(raw);
-  return /** @type {import("./types.js").Binding} */ (/** @type {unknown} */ (raw));
-}
-
-/** @param {Record<string, unknown>} raw */
-function checkSnapshots(raw) {
-  if (
-    raw.base !== null &&
-    (!object(raw.base) ||
-      typeof raw.base.snapshotId !== "string" ||
-      parseStoredManifest(raw.base.manifest).sha256 !== raw.base.manifestSha256)
-  )
-    throw new Error("Invalid source base snapshot.");
-  if (
-    raw.inflight !== null &&
-    (!object(raw.inflight) ||
-      typeof raw.inflight.idempotencyKey !== "string" ||
-      parseStoredManifest(raw.inflight.manifest).sha256 !== raw.inflight.manifestSha256)
-  )
-    throw new Error("Invalid pending source upload.");
-}
-
-/** Project-local state is excluded by the portable source policy. Account/root mismatches fail closed, including copied folders.
- * @returns {import("./adapterTypes.js").SourceStore} */
-export function createProjectShareSourceStore() {
-  /** @param {import("./types.js").BindingKey} key */
-  const location = async (key) => {
-    const dir = await mkdirInside(key.projectPath, ".hyperframes");
-    const environment = createHash("sha256").update(key.backend).digest("hex").slice(0, 16);
-    return join(dir, `share-sync.${environment}.json`);
-  };
-  return {
-    read: async (key) => {
-      const file = await location(key);
-      const handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW).catch((error) => {
-        if (errorCode(error) === "ENOENT") return null;
-        throw error;
-      });
-      if (!handle) return null;
-      try {
-        if (!(await handle.stat()).isFile())
-          throw new Error("Source binding must be a regular file.");
-        return bindingOf(JSON.parse(await handle.readFile("utf8")), key);
-      } finally {
-        await handle.close();
-      }
-    },
-    write: async (binding) => {
-      const file = await location(binding);
-      const held = await lstat(file).catch((error) => {
-        if (errorCode(error) === "ENOENT") return null;
-        throw error;
-      });
-      if (held && !held.isFile()) throw new Error("Source binding must be a regular file.");
-      await writeJsonAtomic(file, binding);
-    },
-  };
-}