blun-king-cli 9.1.486 → 9.1.489

package/agent-spine-plugin/src/lib/graph.js

@@ -0,0 +1,284 @@
+import { readFile, rename, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { buildCatalog } from "./catalog.js";
+import { projectStateDir } from "./paths.js";
+
+const RELATIONS = new Set([
+  "loads", "belongs-to", "explains", "supports", "related",
+  "contradicts", "supersedes-in-relevance"
+]);
+
+const ENTITY_KINDS = new Set(["person", "agent", "group", "channel", "project"]);
+const ENTITY_RELATIONS = new Set([
+  "knows", "works-with", "member-of", "communicates-via",
+  "responsible-for", "reports-to", "related"
+]);
+const ANNOTATION_LAYERS = new Set([
+  "soul", "memory-index", "memory-fact", "reference", "project-reference",
+  "identity", "voice", "conduct", "history"
+]);
+const FORBIDDEN_ATTRIBUTE_KEYS = /^(permissions?|rights?|authorization|credentials?|secrets?|tokens?|api[-_]?keys?)$/i;
+
+function emptyGraph(root) {
+  return {
+    schema: "agentspine.graph/v1",
+    root,
+    edges: [],
+    annotations: [],
+    entities: [],
+    entityEdges: [],
+    history: []
+  };
+}
+
+function normalizeGraph(value, root) {
+  const graph = value && typeof value === "object" ? value : emptyGraph(root);
+  graph.schema = "agentspine.graph/v1";
+  graph.root = root;
+  for (const key of ["edges", "annotations", "entities", "entityEdges", "history"]) {
+    if (!Array.isArray(graph[key])) graph[key] = [];
+  }
+  return graph;
+}
+
+function preservePrevious(graph, kind, value) {
+  if (!value) return;
+  graph.history.push({
+    kind,
+    supersededAt: new Date().toISOString(),
+    value: { ...value, authority: "context-only" },
+    privacy: value.privacy || "private",
+    authority: "context-only"
+  });
+}
+
+function normalizeRelativePath(value, field) {
+  if (!value || typeof value !== "string") throw new Error(`${field} is required`);
+  const normalized = value.replaceAll("\\", "/").replace(/^\.\//, "");
+  if (normalized.startsWith("/") || normalized === ".." || normalized.startsWith("../") || normalized.includes("/../")) {
+    throw new Error(`${field} must be a project-relative path`);
+  }
+  return normalized;
+}
+
+function normalizeConfidence(value) {
+  const number = Number(value);
+  if (!Number.isFinite(number)) throw new Error("confidence must be a finite number");
+  return Math.max(0, Math.min(1, number));
+}
+
+function validateAttributes(value, path = "attributes") {
+  if (value === null || value === undefined) return {};
+  if (Array.isArray(value)) return value.map((item, index) => validateAttributes(item, `${path}[${index}]`));
+  if (typeof value !== "object") return value;
+  const result = {};
+  for (const [key, item] of Object.entries(value)) {
+    if (FORBIDDEN_ATTRIBUTE_KEYS.test(key)) {
+      throw new Error(`${path}.${key} is authority data and cannot be stored in relationship memory`);
+    }
+    result[key] = validateAttributes(item, `${path}.${key}`);
+  }
+  if (Buffer.byteLength(JSON.stringify(result)) > 16384) throw new Error("attributes exceed 16 KiB");
+  return result;
+}
+
+export async function loadGraph(root, providedCatalog = null) {
+  const catalog = providedCatalog || await buildCatalog(root);
+  const directory = await projectStateDir(catalog.root);
+  const path = join(directory, "graph.json");
+  try {
+    const metadata = await stat(path);
+    if (metadata.size > 5 * 1024 * 1024) throw new Error("relationship graph exceeds the 5 MiB read limit");
+    return { graph: normalizeGraph(JSON.parse(await readFile(path, "utf8")), catalog.root), graphPath: path, catalog };
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+    return {
+      graph: emptyGraph(catalog.root),
+      graphPath: path,
+      catalog
+    };
+  }
+}
+
+async function saveGraph(graph, path) {
+  const temporary = `${path}.${process.pid}.tmp`;
+  const content = `${JSON.stringify(graph, null, 2)}\n`;
+  if (Buffer.byteLength(content) > 5 * 1024 * 1024) throw new Error("relationship graph exceeds 5 MiB; archive or compact old observations first");
+  await writeFile(temporary, content, { mode: 0o600 });
+  await rename(temporary, path);
+}
+
+export async function linkDocuments({ root = process.cwd(), from, to, relation = "related", reason = "", confidence = 0.5 }) {
+  if (!RELATIONS.has(relation)) throw new Error(`unsupported relation: ${relation}`);
+  const { graph, graphPath, catalog } = await loadGraph(root);
+  from = normalizeRelativePath(from, "from");
+  to = normalizeRelativePath(to, "to");
+  const known = new Set(catalog.documents.map((document) => document.relativePath));
+  if (!known.has(from)) throw new Error(`unknown source document: ${from}`);
+  if (!known.has(to)) throw new Error(`unknown target document: ${to}`);
+  const edge = {
+    from,
+    to,
+    relation,
+    reason: String(reason).slice(0, 1000),
+    confidence: normalizeConfidence(confidence),
+    updatedAt: new Date().toISOString(),
+    authority: "context-only"
+  };
+  const key = (item) => `${item.from}\0${item.to}\0${item.relation}`;
+  preservePrevious(graph, "document-edge", graph.edges.find((item) => key(item) === key(edge)));
+  graph.edges = graph.edges.filter((item) => key(item) !== key(edge));
+  graph.edges.push(edge);
+  graph.edges.sort((a, b) => key(a).localeCompare(key(b)));
+  await saveGraph(graph, graphPath);
+  return { edge, graphPath };
+}
+
+export async function annotateDocument({ root = process.cwd(), path, layer, reason = "", confidence = 0.5 }) {
+  if (!ANNOTATION_LAYERS.has(layer)) throw new Error(`unsupported context-only layer: ${layer}`);
+  const { graph, graphPath, catalog } = await loadGraph(root);
+  path = normalizeRelativePath(path, "path");
+  if (!catalog.documents.some((document) => document.relativePath === path)) {
+    throw new Error(`unknown document: ${path}`);
+  }
+  const annotation = {
+    path,
+    layer,
+    reason: String(reason).slice(0, 1000),
+    confidence: normalizeConfidence(confidence),
+    updatedAt: new Date().toISOString(),
+    authority: "context-only"
+  };
+  preservePrevious(graph, "document-annotation", graph.annotations.find((item) => item.path === path));
+  graph.annotations = graph.annotations.filter((item) => item.path !== path);
+  graph.annotations.push(annotation);
+  graph.annotations.sort((a, b) => a.path.localeCompare(b.path));
+  await saveGraph(graph, graphPath);
+  return { annotation, graphPath };
+}
+
+export async function upsertEntity({
+  root = process.cwd(), id, kind, displayName = "", aliases = [],
+  attributes = {}, sourceDocument = null, confidence = 0.5, privacy = "private"
+}) {
+  if (!id || !/^[A-Za-z0-9][A-Za-z0-9:_.@/-]{0,127}$/.test(id)) throw new Error("id must be a stable, whitespace-free identifier");
+  if (!ENTITY_KINDS.has(kind)) throw new Error(`unsupported entity kind: ${kind}`);
+  if (!["private", "shared", "group"].includes(privacy)) throw new Error(`unsupported privacy scope: ${privacy}`);
+  if (!attributes || Array.isArray(attributes) || typeof attributes !== "object") throw new Error("attributes must be an object");
+  const { graph, graphPath, catalog } = await loadGraph(root);
+  if (sourceDocument !== null) {
+    sourceDocument = normalizeRelativePath(sourceDocument, "sourceDocument");
+    if (!catalog.documents.some((document) => document.relativePath === sourceDocument)) {
+      throw new Error(`unknown source document: ${sourceDocument}`);
+    }
+  }
+  const entity = {
+    id,
+    kind,
+    displayName: String(displayName).slice(0, 200),
+    aliases: [...new Set((Array.isArray(aliases) ? aliases : []).map((alias) => String(alias).slice(0, 200)))].slice(0, 20),
+    attributes: validateAttributes(attributes),
+    sourceDocument,
+    confidence: normalizeConfidence(confidence),
+    privacy,
+    updatedAt: new Date().toISOString(),
+    authority: "context-only"
+  };
+  preservePrevious(graph, "entity", graph.entities.find((item) => item.id === id));
+  graph.entities = graph.entities.filter((item) => item.id !== id);
+  graph.entities.push(entity);
+  graph.entities.sort((a, b) => a.id.localeCompare(b.id));
+  await saveGraph(graph, graphPath);
+  return { entity, graphPath };
+}
+
+export async function linkEntities({ root = process.cwd(), from, to, relation = "related", reason = "", confidence = 0.5, privacy = "private" }) {
+  if (!ENTITY_RELATIONS.has(relation)) throw new Error(`unsupported entity relation: ${relation}`);
+  if (!["private", "shared", "group"].includes(privacy)) throw new Error(`unsupported privacy scope: ${privacy}`);
+  const { graph, graphPath } = await loadGraph(root);
+  const known = new Set(graph.entities.map((entity) => entity.id));
+  if (!known.has(from)) throw new Error(`unknown source entity: ${from}`);
+  if (!known.has(to)) throw new Error(`unknown target entity: ${to}`);
+  const edge = {
+    from,
+    to,
+    relation,
+    reason: String(reason).slice(0, 1000),
+    confidence: normalizeConfidence(confidence),
+    privacy,
+    updatedAt: new Date().toISOString(),
+    authority: "context-only"
+  };
+  const key = (item) => `${item.from}\0${item.to}\0${item.relation}`;
+  preservePrevious(graph, "entity-edge", graph.entityEdges.find((item) => key(item) === key(edge)));
+  graph.entityEdges = graph.entityEdges.filter((item) => key(item) !== key(edge));
+  graph.entityEdges.push(edge);
+  graph.entityEdges.sort((a, b) => key(a).localeCompare(key(b)));
+  await saveGraph(graph, graphPath);
+  return { edge, graphPath };
+}
+
+export async function unlinkEntities({ root = process.cwd(), from, to, relation = "related" }) {
+  if (!ENTITY_RELATIONS.has(relation)) throw new Error(`unsupported entity relation: ${relation}`);
+  const { graph, graphPath } = await loadGraph(root);
+  const previous = graph.entityEdges.find((item) => item.from === from && item.to === to && item.relation === relation);
+  if (!previous) return { removed: null, duplicate: true, graphPath };
+  preservePrevious(graph, "entity-edge", previous);
+  graph.entityEdges = graph.entityEdges.filter((item) => !(item.from === from && item.to === to && item.relation === relation));
+  await saveGraph(graph, graphPath);
+  return { removed: previous, duplicate: false, graphPath };
+}
+
+function relationshipAudience(graph, groupId) {
+  const ids = new Set([groupId]);
+  for (const edge of graph.entityEdges) {
+    if (edge.relation !== "member-of" || edge.privacy === "private") continue;
+    if (edge.from === groupId) ids.add(edge.to);
+    if (edge.to === groupId) ids.add(edge.from);
+  }
+  return ids;
+}
+
+export async function relationshipContext({
+  root = process.cwd(), entityId, includePrivate = false, groupId = null, catalog: providedCatalog = null
+}) {
+  if (!entityId) throw new Error("entityId is required");
+  const { graph } = await loadGraph(root, providedCatalog);
+  if (groupId !== null) {
+    const group = graph.entities.find((item) => item.id === groupId && item.kind === "group");
+    if (!group) throw new Error(`unknown group entity: ${groupId}`);
+    if (includePrivate) throw new Error("private relationship context cannot be assembled for a group audience");
+  }
+  const entity = graph.entities.find((item) => item.id === entityId);
+  if (!entity) throw new Error(`unknown entity: ${entityId}`);
+  const audience = groupId === null ? null : relationshipAudience(graph, groupId);
+  if (audience && !audience.has(entityId)) throw new Error(`entity is not a visible member of group: ${groupId}`);
+  const visible = (item) => {
+    if (item.privacy === "private") return includePrivate && groupId === null;
+    if (item.privacy === "group" && !audience) return false;
+    if (audience && item.id && !audience.has(item.id)) return false;
+    return true;
+  };
+  if (!visible(entity)) throw new Error(`private relationship context requires includePrivate: ${entityId}`);
+  const entities = new Map(graph.entities.map((item) => [item.id, item]));
+  const visibleEdge = (edge) => visible(edge)
+    && (!audience || [edge.from, edge.to].every((id) => audience.has(id)))
+    && [edge.from, edge.to].every((id) => !entities.has(id) || visible(entities.get(id)));
+  const edges = graph.entityEdges.filter((edge) => (edge.from === entityId || edge.to === entityId) && visibleEdge(edge));
+  const ids = new Set(edges.flatMap((edge) => [edge.from, edge.to]));
+  ids.add(entityId);
+  return {
+    entity,
+    relatedEntities: graph.entities.filter((item) => ids.has(item.id) && visible(item)),
+    edges,
+    history: graph.history.filter((entry) => {
+      if (!visible(entry)) return false;
+      const value = entry.value || {};
+      if (value.id && entities.has(value.id) && !visible(entities.get(value.id))) return false;
+      if ((value.from || value.to) && !visibleEdge(value)) return false;
+      return value.id === entityId || value.from === entityId || value.to === entityId;
+    }),
+    groupId,
+    authority: "context-only"
+  };
+}

package/agent-spine-plugin/src/lib/https-transport.js

@@ -0,0 +1,392 @@
+import { createHash, randomUUID } from "node:crypto";
+import { lookup as dnsLookup } from "node:dns/promises";
+import { lstat, mkdir, mkdtemp, open, readFile, realpath, rm, writeFile } from "node:fs/promises";
+import { request as httpsRequest } from "node:https";
+import { BlockList, isIP } from "node:net";
+import { tmpdir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+import { verifyEnvelope } from "./authentication.js";
+import { buildCatalog } from "./catalog.js";
+import { isInside } from "./paths.js";
+import { pullShared, readDirectoryExchange, validateSharedEvent } from "./sharing.js";
+
+const SCHEMA = "agentspine.https-snapshot/v1";
+const CONFIRMATION = "local-share-confirmed";
+const MAX_EVENTS = 2000;
+const MAX_SNAPSHOT_BYTES = 21 * 1024 * 1024;
+const MAX_TOKEN_BYTES = 8192;
+const ID_RE = /^[A-Za-z0-9][A-Za-z0-9:_.@/-]{0,127}$/;
+const DIGEST_RE = /^[a-f0-9]{64}$/;
+const TOKEN_ENV_RE = /^[A-Z_][A-Z0-9_]{0,127}$/;
+
+const blockedAddresses = new BlockList();
+const publicIpv6 = new BlockList();
+publicIpv6.addSubnet("2000::", 3, "ipv6");
+for (const [network, prefix] of [
+  ["0.0.0.0", 8], ["10.0.0.0", 8], ["100.64.0.0", 10], ["127.0.0.0", 8],
+  ["169.254.0.0", 16], ["172.16.0.0", 12], ["192.0.0.0", 24], ["192.0.2.0", 24],
+  ["192.168.0.0", 16], ["198.18.0.0", 15], ["198.51.100.0", 24],
+  ["203.0.113.0", 24], ["224.0.0.0", 4], ["240.0.0.0", 4]
+]) blockedAddresses.addSubnet(network, prefix, "ipv4");
+for (const [network, prefix] of [
+  ["::", 128], ["::1", 128], ["64:ff9b::", 96],
+  ["100::", 64], ["2001::", 32], ["2001:2::", 48], ["2001:10::", 28],
+  ["2001:20::", 28], ["2001:db8::", 32], ["2002::", 16], ["3fff::", 20],
+  ["fc00::", 7], ["fe80::", 10], ["ff00::", 8]
+]) blockedAddresses.addSubnet(network, prefix, "ipv6");
+
+function canonical(value) {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function digest(value) {
+  return createHash("sha256").update(canonical(value)).digest("hex");
+}
+
+function exactKeys(value, expected) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const actual = Object.keys(value).sort();
+  const wanted = [...expected].sort();
+  return actual.length === wanted.length && actual.every((key, index) => key === wanted[index]);
+}
+
+function validDate(value) {
+  return typeof value === "string" && value.length > 0 && Number.isFinite(new Date(value).getTime());
+}
+
+function withoutDigest(value) {
+  const { digest: _digest, ...body } = value;
+  return body;
+}
+
+function eventId(document) {
+  const payload = document?.schema === "agentspine.signed-envelope/v1" ? document.payload : null;
+  return payload?.id;
+}
+
+function eventFilename(id) {
+  return `${createHash("sha256").update(id).digest("hex")}.json`;
+}
+
+async function prospectiveCanonicalPath(path) {
+  let ancestor = path;
+  const missing = [];
+  while (true) {
+    try {
+      const canonicalAncestor = await realpath(ancestor);
+      return resolve(canonicalAncestor, ...missing.reverse());
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+      const parent = dirname(ancestor);
+      if (parent === ancestor) throw error;
+      missing.push(basename(ancestor));
+      ancestor = parent;
+    }
+  }
+}
+
+export function validateHttpsEndpoint(value) {
+  let endpoint;
+  try {
+    endpoint = new URL(value);
+  } catch {
+    throw new Error("HTTPS snapshot URL is invalid");
+  }
+  if (endpoint.protocol !== "https:") throw new Error("HTTPS snapshots require an https:// URL");
+  if (endpoint.username || endpoint.password) throw new Error("credentials must not be embedded in an HTTPS snapshot URL");
+  if (endpoint.search || endpoint.hash) throw new Error("HTTPS snapshot URLs cannot contain a query or fragment");
+  if (!endpoint.hostname || endpoint.pathname.endsWith("/")) {
+    throw new Error("HTTPS snapshot URL must identify one explicit JSON resource");
+  }
+  return endpoint;
+}
+
+function addressBlocked(address) {
+  const family = isIP(address);
+  if (!family) throw new Error(`DNS returned an invalid address: ${address}`);
+  if (family === 6 && !publicIpv6.check(address, "ipv6")) return true;
+  return blockedAddresses.check(address, family === 4 ? "ipv4" : "ipv6");
+}
+
+async function within(promise, milliseconds, message) {
+  let timer;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise((_resolve, reject) => {
+        timer = setTimeout(() => reject(new Error(message)), milliseconds);
+      })
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export async function resolveHttpsEndpoint(endpoint, {
+  allowPrivateNetwork = false, lookup = dnsLookup
+} = {}) {
+  const parsed = endpoint instanceof URL ? endpoint : validateHttpsEndpoint(endpoint);
+  const lookupHostname = parsed.hostname.startsWith("[") && parsed.hostname.endsWith("]")
+    ? parsed.hostname.slice(1, -1) : parsed.hostname;
+  const literalFamily = isIP(lookupHostname);
+  const answers = literalFamily
+    ? [{ address: lookupHostname, family: literalFamily }]
+    : await lookup(lookupHostname, { all: true, verbatim: true });
+  if (!Array.isArray(answers) || answers.length === 0) throw new Error("HTTPS snapshot host did not resolve");
+  for (const answer of answers) {
+    if (!answer || isIP(answer.address) !== Number(answer.family)) throw new Error("HTTPS snapshot DNS result is invalid");
+    if (!allowPrivateNetwork && addressBlocked(answer.address)) {
+      throw new Error("HTTPS snapshot host resolves to a private, local, reserved, or documentation address");
+    }
+  }
+  return {
+    endpoint: parsed, lookupHostname,
+    addresses: answers.map((answer) => ({ address: answer.address, family: Number(answer.family) }))
+  };
+}
+
+function bearerToken(tokenEnv, environment) {
+  if (tokenEnv === null || tokenEnv === undefined) return null;
+  if (!TOKEN_ENV_RE.test(tokenEnv)) throw new Error("tokenEnv must be an uppercase environment variable name");
+  const value = environment[tokenEnv];
+  if (typeof value !== "string" || !value) throw new Error(`HTTPS snapshot token environment variable is missing: ${tokenEnv}`);
+  if (Buffer.byteLength(value) > MAX_TOKEN_BYTES || /[\0-\x1f\x7f]/.test(value)) {
+    throw new Error("HTTPS snapshot bearer token is invalid");
+  }
+  return value;
+}
+
+export async function fetchHttpsSnapshot({
+  url, tokenEnv = null, timeoutMs = 10000, allowPrivateNetwork = false,
+  confirmation = null, environment = process.env, lookup = dnsLookup, request = httpsRequest
+}) {
+  if (!Number.isInteger(timeoutMs) || timeoutMs < 1000 || timeoutMs > 30000) {
+    throw new Error("HTTPS snapshot timeout must be between 1000 and 30000 milliseconds");
+  }
+  if (allowPrivateNetwork && confirmation !== CONFIRMATION) {
+    throw new Error("private-network HTTPS access requires explicit local owner confirmation");
+  }
+  const resolved = await within(
+    resolveHttpsEndpoint(validateHttpsEndpoint(url), { allowPrivateNetwork, lookup }),
+    timeoutMs,
+    "HTTPS snapshot DNS resolution timed out"
+  );
+  const token = bearerToken(tokenEnv, environment);
+  const selected = resolved.addresses[0];
+  const headers = {
+    accept: "application/json",
+    "accept-encoding": "identity",
+    "user-agent": "AgentSpine/0.1 HTTPS snapshot transport"
+  };
+  if (token) headers.authorization = `Bearer ${token}`;
+  const body = await new Promise((resolvePromise, rejectPromise) => {
+    let deadline;
+    const reject = (error) => {
+      clearTimeout(deadline);
+      rejectPromise(error);
+    };
+    const resolve = (value) => {
+      clearTimeout(deadline);
+      resolvePromise(value);
+    };
+    const requestOptions = {
+      protocol: "https:", hostname: resolved.lookupHostname,
+      port: resolved.endpoint.port || 443,
+      path: resolved.endpoint.pathname, method: "GET", headers,
+      agent: false, autoSelectFamily: false,
+      servername: isIP(resolved.lookupHostname) ? undefined : resolved.lookupHostname,
+      lookup: (_hostname, options, callback) => {
+        const family = typeof options === "object" && options.family ? Number(options.family) : 0;
+        const usable = family ? resolved.addresses.find((item) => item.family === family) : selected;
+        if (!usable) return callback(new Error("no vetted DNS address matches the requested family"));
+        return callback(null, usable.address, usable.family);
+      }
+    };
+    const active = request(requestOptions, (response) => {
+      const status = Number(response.statusCode || 0);
+      if (status >= 300 && status < 400) {
+        response.resume();
+        reject(new Error("HTTPS snapshot redirects are not followed"));
+        return;
+      }
+      if (status !== 200) {
+        response.resume();
+        reject(new Error(`HTTPS snapshot request failed with status ${status}`));
+        return;
+      }
+      const contentType = String(response.headers["content-type"] || "").toLowerCase();
+      if (!/^application\/(?:json|[a-z0-9.+-]+\+json)(?:\s*;|$)/.test(contentType)) {
+        response.resume();
+        reject(new Error("HTTPS snapshot response must use an application/json content type"));
+        return;
+      }
+      const encoding = String(response.headers["content-encoding"] || "identity").toLowerCase();
+      if (encoding !== "identity") {
+        response.resume();
+        reject(new Error("compressed HTTPS snapshots are rejected to keep byte limits exact"));
+        return;
+      }
+      const declared = Number(response.headers["content-length"] || 0);
+      if (declared && (!Number.isSafeInteger(declared) || declared > MAX_SNAPSHOT_BYTES)) {
+        response.resume();
+        reject(new Error("HTTPS snapshot exceeds the 21 MiB response limit"));
+        return;
+      }
+      const chunks = [];
+      let bytes = 0;
+      response.on("data", (chunk) => {
+        bytes += chunk.length;
+        if (bytes > MAX_SNAPSHOT_BYTES) {
+          active.destroy(new Error("HTTPS snapshot exceeds the 21 MiB response limit"));
+          return;
+        }
+        chunks.push(chunk);
+      });
+      response.on("end", () => resolve(Buffer.concat(chunks)));
+      response.on("error", reject);
+    });
+    active.setTimeout(timeoutMs, () => active.destroy(new Error("HTTPS snapshot request timed out")));
+    deadline = setTimeout(() => active.destroy(new Error("HTTPS snapshot request timed out")), timeoutMs);
+    active.on("error", reject);
+    active.end();
+  });
+  let snapshot;
+  try {
+    snapshot = JSON.parse(body.toString("utf8"));
+  } catch {
+    throw new Error("HTTPS snapshot response is not valid JSON");
+  }
+  return {
+    snapshot: validateHttpsSnapshot(snapshot),
+    endpoint: `${resolved.endpoint.origin}${resolved.endpoint.pathname}`,
+    authenticatedRequest: Boolean(token)
+  };
+}
+
+export function validateHttpsSnapshot(snapshot) {
+  if (!exactKeys(snapshot, [
+    "schema", "snapshotId", "scopeId", "adapterId", "generatedAt",
+    "manifest", "events", "authority", "digest"
+  ]) || snapshot.schema !== SCHEMA || !ID_RE.test(snapshot.snapshotId || "")
+    || !ID_RE.test(snapshot.scopeId || "") || !ID_RE.test(snapshot.adapterId || "")
+    || !validDate(snapshot.generatedAt) || snapshot.authority !== "context-only"
+    || !DIGEST_RE.test(snapshot.digest || "") || digest(withoutDigest(snapshot)) !== snapshot.digest
+    || !Array.isArray(snapshot.events) || snapshot.events.length > MAX_EVENTS) {
+    throw new Error("HTTPS snapshot is invalid or has failed its integrity check");
+  }
+  if (Buffer.byteLength(JSON.stringify(snapshot)) > MAX_SNAPSHOT_BYTES) {
+    throw new Error("HTTPS snapshot exceeds the 21 MiB validation limit");
+  }
+  const verifiedManifest = verifyEnvelope(snapshot.manifest, "manifest");
+  if (verifiedManifest.payload?.scopeId !== snapshot.scopeId
+    || verifiedManifest.payload?.adapterId !== snapshot.adapterId
+    || verifiedManifest.payload?.adapter !== "directory") {
+    throw new Error("HTTPS snapshot metadata does not match its signed manifest");
+  }
+  const seen = new Map();
+  for (const document of snapshot.events) {
+    const verified = verifyEnvelope(document, "event");
+    const event = validateSharedEvent(verified.payload, snapshot.scopeId);
+    const previous = seen.get(event.id);
+    if (previous && previous !== event.digest) throw new Error(`HTTPS snapshot event ID collision: ${event.id}`);
+    if (previous) throw new Error(`HTTPS snapshot contains duplicate event: ${event.id}`);
+    seen.set(event.id, event.digest);
+  }
+  return snapshot;
+}
+
+export async function buildHttpsSnapshot({
+  root = process.cwd(), directory, snapshotId = `snapshot:${randomUUID()}`, now = new Date()
+}) {
+  if (!ID_RE.test(snapshotId || "")) throw new Error("snapshotId must be a stable, whitespace-free identifier");
+  const exchange = await readDirectoryExchange({ root, directory, requireAuthenticated: true });
+  const generatedAt = new Date(now).toISOString();
+  if (!validDate(generatedAt)) throw new Error("now must be a valid date");
+  const body = {
+    schema: SCHEMA, snapshotId, scopeId: exchange.scopeId, adapterId: exchange.adapterId,
+    generatedAt, manifest: exchange.manifest, events: exchange.events,
+    authority: "context-only"
+  };
+  return validateHttpsSnapshot({ ...body, digest: digest(body) });
+}
+
+export async function exportHttpsSnapshot({
+  root = process.cwd(), directory, output, snapshotId = `snapshot:${randomUUID()}`,
+  confirmation, now = new Date()
+}) {
+  if (confirmation !== CONFIRMATION) throw new Error("HTTPS snapshot export requires explicit local owner confirmation");
+  if (!output || typeof output !== "string") throw new Error("HTTPS snapshot output path is required");
+  const snapshot = await buildHttpsSnapshot({ root, directory, snapshotId, now });
+  const catalog = await buildCatalog(root);
+  const target = resolve(output);
+  const prospectiveTarget = await prospectiveCanonicalPath(target);
+  if (isInside(catalog.root, prospectiveTarget)) {
+    throw new Error("HTTPS snapshot output must remain outside the scanned project");
+  }
+  let parent = dirname(target);
+  await mkdir(parent, { recursive: true, mode: 0o700 });
+  parent = await realpath(parent);
+  if (isInside(catalog.root, parent)) {
+    throw new Error("HTTPS snapshot output must remain outside the scanned project");
+  }
+  try {
+    await lstat(target);
+    throw new Error("HTTPS snapshot output already exists; choose a new path");
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  const content = `${JSON.stringify(snapshot, null, 2)}\n`;
+  if (Buffer.byteLength(content) > MAX_SNAPSHOT_BYTES) throw new Error("HTTPS snapshot exceeds the 21 MiB export limit");
+  const handle = await open(target, "wx", 0o600);
+  try {
+    await handle.writeFile(content, "utf8");
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  return {
+    created: true, output: target, snapshotId: snapshot.snapshotId,
+    scopeId: snapshot.scopeId, adapterId: snapshot.adapterId,
+    events: snapshot.events.length, digest: snapshot.digest,
+    authority: "context-only"
+  };
+}
+
+export async function importHttpsSnapshot({ root = process.cwd(), snapshot, now = new Date() }) {
+  const validated = validateHttpsSnapshot(structuredClone(snapshot));
+  const directory = await mkdtemp(join(tmpdir(), "agentspine-https-snapshot-"));
+  try {
+    const eventsDirectory = join(directory, "events");
+    await mkdir(eventsDirectory, { mode: 0o700 });
+    await writeFile(
+      join(directory, ".agentspine-exchange.json"),
+      `${JSON.stringify(validated.manifest, null, 2)}\n`, { mode: 0o600 }
+    );
+    for (const document of validated.events) {
+      const id = eventId(document);
+      await writeFile(join(eventsDirectory, eventFilename(id)), `${JSON.stringify(document, null, 2)}\n`, {
+        mode: 0o600, flag: "wx"
+      });
+    }
+    const result = await pullShared({ root, directory, requireAuthenticated: true, now });
+    return {
+      ...result, transport: "https-snapshot", snapshotId: validated.snapshotId,
+      snapshotDigest: validated.digest, authority: "context-only"
+    };
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+}
+
+export async function pullHttpsSnapshot(options) {
+  const fetched = await fetchHttpsSnapshot(options);
+  const imported = await importHttpsSnapshot({ root: options.root, snapshot: fetched.snapshot, now: options.now });
+  return {
+    ...imported, endpoint: fetched.endpoint,
+    authenticatedRequest: fetched.authenticatedRequest
+  };
+}