stylegallery 0.1.0 → 0.1.2

package/scripts/agent-native/v2/extensions/agui-projection.mjs

@@ -0,0 +1,191 @@
+import { canonicalize, cloneAndFreeze, hashCanonical } from "../../canonical-json.mjs";
+
+const TERMINAL = new Set(["RUN_FINISHED", "RUN_ERROR"]);
+const EVENT_TYPES = new Set([
+  "RUN_STARTED", "RUN_FINISHED", "RUN_ERROR",
+  "TEXT_MESSAGE_START", "TEXT_MESSAGE_CONTENT", "TEXT_MESSAGE_END",
+  "TOOL_CALL_START", "TOOL_CALL_ARGS", "TOOL_CALL_ARGUMENTS", "TOOL_CALL_END",
+  "STATE_SNAPSHOT", "STATE_DELTA",
+]);
+
+export class AgUiProjectionError extends TypeError {
+  constructor(code, message, path = "") {
+    super(message);
+    this.name = "AgUiProjectionError";
+    this.code = code;
+    if (path) this.path = path;
+  }
+}
+
+function pick(value, ...keys) {
+  if (!value || typeof value !== "object") return undefined;
+  for (const key of keys) if (Object.hasOwn(value, key) && value[key] !== undefined) return value[key];
+  return undefined;
+}
+
+function text(value, fallback) {
+  return typeof value === "string" && value.length > 0 ? value : fallback;
+}
+
+function domainId(value, ...keys) {
+  return text(pick(value, ...keys, "stable_ref", "stableRef", "id"), "unknown");
+}
+
+function bindingIds(binding, task, run) {
+  const bindingId = text(pick(binding, "binding_id", "bindingId", "protocol_binding_id", "protocolBindingId"), "sg:binding/agui");
+  const taskId = domainId(task, "task_id", "taskId");
+  const runId = domainId(run, "run_id", "runId");
+  const taskProtocolId = text(
+    pick(binding, "agui_task_id", "aguiTaskId", "protocol_task_id", "protocolTaskId", "protocolTask"),
+    `agui-task-${hashCanonical({ bindingId, taskId }).slice(7, 23)}`,
+  );
+  const runProtocolId = text(
+    pick(binding, "agui_run_id", "aguiRunId", "protocol_run_id", "protocolRunId", "protocolRun"),
+    `agui-run-${hashCanonical({ bindingId, runId }).slice(7, 23)}`,
+  );
+  const threadId = text(pick(binding, "thread_id", "threadId", "agui_thread_id", "aguiThreadId"), taskProtocolId);
+  return { bindingId, domainTaskId: taskId, domainRunId: runId, taskProtocolId, runProtocolId, threadId };
+}
+
+function eventType(event) {
+  return String(pick(event, "type", "eventType", "event_type", "name") ?? "")
+    .trim().toUpperCase().replaceAll("-", "_");
+}
+
+function asEvents(input) {
+  if (Array.isArray(input)) return input;
+  return pick(input, "events", "items") ?? null;
+}
+
+function failure(code, message, path) {
+  return path ? { code, message, path } : { code, message };
+}
+
+/** Validate an AG-UI event sequence before it crosses the protocol boundary. */
+export function validateAgUiTransitions(input) {
+  const events = asEvents(input);
+  const failures = [];
+  if (!Array.isArray(events)) return { ok: false, valid: false, failures: [failure("agui_events_required", "events must be an array", "events")] };
+  if (events.length === 0) failures.push(failure("agui_events_empty", "AG-UI event sequence cannot be empty", "events"));
+  let started = false;
+  let ended = false;
+  let openTextId = null;
+  let openToolId = null;
+  let runId = null;
+  let terminalCount = 0;
+  for (let index = 0; index < events.length; index += 1) {
+    const event = events[index];
+    const type = eventType(event);
+    const path = `/events/${index}`;
+    if (!event || typeof event !== "object" || Array.isArray(event)) {
+      failures.push(failure("agui_event_invalid", "event must be an object", path));
+      continue;
+    }
+    if (!EVENT_TYPES.has(type)) failures.push(failure("agui_event_type_invalid", `unsupported AG-UI event type ${type || "<empty>"}`, `${path}/type`));
+    const eventRunId = pick(event, "runId", "run_id");
+    if (eventRunId !== undefined && runId !== null && eventRunId !== runId) failures.push(failure("agui_run_id_mismatch", "all events must use one protocol run ID", `${path}/runId`));
+    if (eventRunId !== undefined) runId = eventRunId;
+    if (ended) failures.push(failure("agui_event_after_terminal", "no event may follow a terminal event", path));
+    if (type === "RUN_STARTED") {
+      if (started) failures.push(failure("agui_run_started_duplicate", "RUN_STARTED may occur only once", path));
+      if (index !== 0) failures.push(failure("agui_run_started_not_first", "RUN_STARTED must be the first event", path));
+      started = true;
+      continue;
+    }
+    if (!started) failures.push(failure("agui_run_not_started", "event cannot precede RUN_STARTED", path));
+    if (TERMINAL.has(type)) {
+      terminalCount += 1;
+      ended = true;
+      if (openTextId !== null) failures.push(failure("agui_text_message_open", "terminal event closed an open text message", path));
+      if (openToolId !== null) failures.push(failure("agui_tool_call_open", "terminal event closed an open tool call", path));
+      continue;
+    }
+    if (type === "TEXT_MESSAGE_START") {
+      const current = pick(event, "messageId", "message_id");
+      if (typeof current !== "string" || current.length === 0) failures.push(failure("agui_message_id_required", "TEXT_MESSAGE_START requires messageId", `${path}/messageId`));
+      if (openTextId !== null) failures.push(failure("agui_text_message_nested", "text messages cannot be nested", path));
+      openTextId = current ?? null;
+    } else if (type === "TEXT_MESSAGE_CONTENT") {
+      const current = pick(event, "messageId", "message_id");
+      if (openTextId === null || current !== openTextId) failures.push(failure("agui_text_message_not_open", "TEXT_MESSAGE_CONTENT must target an open message", path));
+    } else if (type === "TEXT_MESSAGE_END") {
+      const current = pick(event, "messageId", "message_id");
+      if (openTextId === null || current !== openTextId) failures.push(failure("agui_text_message_not_open", "TEXT_MESSAGE_END must target an open message", path));
+      openTextId = null;
+    } else if (type === "TOOL_CALL_START") {
+      const current = pick(event, "toolCallId", "tool_call_id");
+      if (typeof current !== "string" || current.length === 0) failures.push(failure("agui_tool_call_id_required", "TOOL_CALL_START requires toolCallId", `${path}/toolCallId`));
+      if (openToolId !== null) failures.push(failure("agui_tool_call_nested", "tool calls cannot be nested", path));
+      openToolId = current ?? null;
+    } else if (type === "TOOL_CALL_ARGS" || type === "TOOL_CALL_ARGUMENTS") {
+      const current = pick(event, "toolCallId", "tool_call_id");
+      if (openToolId === null || current !== openToolId) failures.push(failure("agui_tool_call_not_open", "TOOL_CALL_ARGS must target an open tool call", path));
+    } else if (type === "TOOL_CALL_END") {
+      const current = pick(event, "toolCallId", "tool_call_id");
+      if (openToolId === null || current !== openToolId) failures.push(failure("agui_tool_call_not_open", "TOOL_CALL_END must target an open tool call", path));
+      openToolId = null;
+    }
+  }
+  if (!started) failures.push(failure("agui_run_started_required", "sequence must contain RUN_STARTED", "events"));
+  if (terminalCount !== 1) failures.push(failure("agui_terminal_count_invalid", "sequence must contain exactly one terminal event", "events"));
+  if (terminalCount === 1 && !TERMINAL.has(eventType(events.at(-1)))) failures.push(failure("agui_terminal_not_last", "terminal event must be last", `/events/${events.length - 1}`));
+  if (openTextId !== null) failures.push(failure("agui_text_message_unclosed", "text message did not receive TEXT_MESSAGE_END", "events"));
+  if (openToolId !== null) failures.push(failure("agui_tool_call_unclosed", "tool call did not receive TOOL_CALL_END", "events"));
+  return { ok: failures.length === 0, valid: failures.length === 0, failures };
+}
+
+function protocolEvent(type, ids, fields = {}) {
+  return { type, runId: ids.runProtocolId, ...fields };
+}
+
+/** Project a domain Task/Run outcome to one deterministic AG-UI 0.0.57 stream. */
+export function projectAgUiEvents(input = {}) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) throw new AgUiProjectionError("agui_input_invalid", "projectAgUiEvents expects an object");
+  const ids = bindingIds(pick(input, "protocolBinding", "protocol_binding") ?? {}, input.task ?? {}, input.run ?? {});
+  const textValue = String(pick(input, "text", "message") ?? "");
+  const messageValue = pick(input, "messageId", "message_id") ?? `${ids.runProtocolId}:message`;
+  const tool = pick(input, "toolCall", "tool_call") ?? {};
+  const toolId = text(pick(tool, "id", "toolCallId", "tool_call_id"), `${ids.runProtocolId}:tool`);
+  const toolName = text(pick(tool, "name", "toolName", "tool_name"), "operation");
+  const toolArgs = pick(tool, "args", "arguments") ?? {};
+  const state = pick(input, "state", "snapshot") ?? {};
+  const outcome = String(pick(input, "outcome", "status") ?? pick(input.run, "state", "status") ?? pick(input.task, "state", "status") ?? "COMPLETED").toUpperCase();
+  const success = new Set(["COMPLETED", "SUCCEEDED", "SUCCESS", "OK", "PASS", "PASSED"]).has(outcome);
+  const correlation = { protocolBindingId: ids.bindingId, domainTaskId: ids.domainTaskId, domainRunId: ids.domainRunId };
+  const events = [
+    protocolEvent("RUN_STARTED", ids, { threadId: ids.threadId, input: pick(input.task, "intent", "request") ?? {}, metadata: correlation }),
+    protocolEvent("TEXT_MESSAGE_START", ids, { messageId: messageValue, role: "assistant" }),
+    protocolEvent("TEXT_MESSAGE_CONTENT", ids, { messageId: messageValue, delta: textValue }),
+    protocolEvent("TEXT_MESSAGE_END", ids, { messageId: messageValue }),
+    protocolEvent("TOOL_CALL_START", ids, { toolCallId: toolId, toolCallName: toolName }),
+    protocolEvent("TOOL_CALL_ARGS", ids, { toolCallId: toolId, delta: typeof toolArgs === "string" ? toolArgs : canonicalize(toolArgs) }),
+    protocolEvent("TOOL_CALL_END", ids, { toolCallId: toolId }),
+    protocolEvent("STATE_SNAPSHOT", ids, { snapshot: state }),
+    success
+      ? protocolEvent("RUN_FINISHED", ids, { threadId: ids.threadId, result: pick(input, "result", "output") ?? { status: outcome } })
+      : protocolEvent("RUN_ERROR", ids, { threadId: ids.threadId, message: text(pick(input, "error", "errorMessage"), outcome) }),
+  ];
+  const validation = validateAgUiTransitions(events);
+  if (!validation.ok) throw new AgUiProjectionError("agui_projection_invalid", "generated event sequence failed transition validation");
+  return cloneAndFreeze({ ok: true, events, protocolBinding: { ...correlation, protocol: "ag-ui" }, protocolIds: { threadId: ids.threadId, taskId: ids.taskProtocolId, runId: ids.runProtocolId } });
+}
+
+export const projectAGUIEvents = projectAgUiEvents;
+export const projectAguiEvents = projectAgUiEvents;
+export const createAgUiEvents = projectAgUiEvents;
+export const validateAGUITransitions = validateAgUiTransitions;
+export const assertAgUiTransitions = validateAgUiTransitions;
+export const validateEventSequence = validateAgUiTransitions;
+
+export const AG_UI_EXPERIMENTAL_EXTENSION = Object.freeze({
+  protocol: "ag-ui",
+  version: "0.0.57",
+  operations: Object.freeze({
+    "events.project": projectAgUiEvents,
+    "events.validate": validateAgUiTransitions,
+  }),
+});
+
+export function registerAgUiExtension(registry) {
+  return registry.register(AG_UI_EXPERIMENTAL_EXTENSION);
+}

package/scripts/agent-native/v2/material-admission.mjs

@@ -0,0 +1,295 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import Ajv2020 from "ajv/dist/2020.js";
+
+import { canonicalize, deepFreeze } from "../canonical-json.mjs";
+
+const moduleDirectory = path.dirname(fileURLToPath(import.meta.url));
+const v2Directory = path.resolve(moduleDirectory, "../../../consumer-reference/agent-native/v2");
+const policyPath = path.join(v2Directory, "admission-policy.json");
+const policySchemaPath = path.join(v2Directory, "schema/admission-policy.schema.json");
+const recordSchemaPath = path.join(v2Directory, "schema/material-record.schema.json");
+const manifestSchemaPath = path.join(v2Directory, "schema/material-manifest.schema.json");
+const MANIFEST_REF = "sg:manifest/material-admission-v2";
+const MATERIAL_REF_PATTERN = /^sg:material\/path-sha256-[a-f0-9]{64}$/;
+const MATERIAL_VERSION_PATTERN = /^sg:material\/path-sha256-[a-f0-9]{64}@sha256:[a-f0-9]{64}$/;
+const HASH_PATTERN = /^[a-f0-9]{64}$/;
+const DOMAINS = new Set(["layout", "motion", "design-engineering", "game-ui", "platform-guides", "shared"]);
+const LIFECYCLES = new Set(["draft", "stable", "deprecated", "experimental", "generated"]);
+const RECORD_KEYS = new Set(["schema_version", "record_kind", "stable_ref", "version_id", "repository_path", "media_type", "source_sha256", "byte_length", "lifecycle", "domain"]);
+const MANIFEST_KEYS = new Set(["schema_version", "record_kind", "stable_ref", "version_id", "admission_policy_ref", "admission_policy_version_id", "materials"]);
+
+export class MaterialAdmissionError extends TypeError {
+  constructor(code, message, sourcePath) {
+    super(message);
+    this.name = "MaterialAdmissionError";
+    this.code = code;
+    if (sourcePath !== undefined) this.path = sourcePath;
+  }
+}
+
+function parseJsonFile(sourcePath) { return JSON.parse(fs.readFileSync(sourcePath, "utf8")); }
+function failure(code, message, sourcePath) { return { code, message, ...(sourcePath === undefined ? {} : { path: sourcePath }) }; }
+function sha256(bytes) { return createHash("sha256").update(bytes).digest("hex"); }
+function canonicalVersionId(stableRef, value) {
+  const payload = { ...value };
+  delete payload.version_id;
+  return `${stableRef}@sha256:${sha256(Buffer.from(canonicalize(payload), "utf8"))}`;
+}
+function bytewiseCompare(left, right) { return Buffer.compare(Buffer.from(left, "utf8"), Buffer.from(right, "utf8")); }
+
+const policySchema = parseJsonFile(policySchemaPath);
+const recordSchema = parseJsonFile(recordSchemaPath);
+const manifestSchema = parseJsonFile(manifestSchemaPath);
+const ajv = new Ajv2020({ allErrors: true, strict: true });
+ajv.addSchema(policySchema);
+ajv.addSchema(recordSchema);
+ajv.addSchema(manifestSchema);
+const validatePolicySchema = ajv.getSchema(policySchema.$id);
+const validateRecordSchema = ajv.getSchema(recordSchema.$id);
+const validateManifestSchema = ajv.getSchema(manifestSchema.$id);
+
+export function validateMaterialAdmissionPolicy(policy) {
+  const failures = [];
+  if (!validatePolicySchema(policy)) failures.push(failure("material_policy_schema_invalid", "admission policy does not satisfy its closed schema"));
+  if (failures.length === 0) {
+    const paths = policy.allowed_materials.map(({ repository_path }) => repository_path);
+    if (new Set(paths).size !== paths.length) failures.push(failure("material_policy_path_duplicate", "admission policy paths must be unique"));
+    if (paths.some((entry, index) => index > 0 && bytewiseCompare(paths[index - 1], entry) >= 0)) failures.push(failure("material_policy_order_invalid", "admission policy paths must be bytewise sorted"));
+    const exclusions = policy.exclusions.map(({ kind, value }) => `${kind}\0${value}`);
+    if (new Set(exclusions).size !== exclusions.length) failures.push(failure("material_policy_exclusion_duplicate", "admission policy exclusions must be unique"));
+    if (policy.version_id !== canonicalVersionId(policy.stable_ref, policy)) failures.push(failure("material_policy_version_invalid", "admission policy VersionID does not bind canonical policy content"));
+  }
+  return deepFreeze({ ok: failures.length === 0, failures });
+}
+
+const loadedPolicy = parseJsonFile(policyPath);
+const loadedPolicyResult = validateMaterialAdmissionPolicy(loadedPolicy);
+if (!loadedPolicyResult.ok) throw new MaterialAdmissionError(loadedPolicyResult.failures[0].code, loadedPolicyResult.failures[0].message);
+export const materialAdmissionPolicy = deepFreeze(loadedPolicy);
+const allowedRoutes = new Map(materialAdmissionPolicy.allowed_materials.map((entry) => [entry.repository_path, entry]));
+
+function normalizedPathFailure(repositoryPath) {
+  if (typeof repositoryPath !== "string" || repositoryPath.length === 0 || repositoryPath.includes("\0")
+    || /(?:[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF])/.test(repositoryPath)) {
+    return failure("material_path_invalid", "repository_path must be a non-empty valid Unicode string", repositoryPath);
+  }
+  if (path.posix.isAbsolute(repositoryPath) || path.win32.isAbsolute(repositoryPath)
+    || /^[A-Za-z][A-Za-z0-9+.-]*:\/\//.test(repositoryPath)) {
+    return failure("material_path_absolute", "repository_path must be repository-relative and not a URI", repositoryPath);
+  }
+  const components = repositoryPath.split("/");
+  if (repositoryPath.includes("\\") || components.some((component) => component === "" || component === ".")) {
+    return failure("material_path_not_normalized", "repository_path must use normalized forward-slash components", repositoryPath);
+  }
+  if (components.includes("..")) return failure("material_path_escape", "repository_path must not contain parent components", repositoryPath);
+  if (path.posix.normalize(repositoryPath) !== repositoryPath) return failure("material_path_not_normalized", "repository_path must be normalized", repositoryPath);
+  return null;
+}
+
+export function materialStableRefForPath(repositoryPath) {
+  const pathFailure = normalizedPathFailure(repositoryPath);
+  if (pathFailure) throw new MaterialAdmissionError(pathFailure.code, pathFailure.message, repositoryPath);
+  return `sg:material/path-sha256-${sha256(Buffer.from(repositoryPath, "utf8"))}`;
+}
+
+export function materialVersionIdForSource(stableRef, sourceSha256) {
+  if (!MATERIAL_REF_PATTERN.test(stableRef ?? "") || !HASH_PATTERN.test(sourceSha256 ?? "")) {
+    throw new MaterialAdmissionError("material_identity_input_invalid", "source VersionID requires a v2 material StableRef and lowercase SHA-256");
+  }
+  return `${stableRef}@sha256:${sourceSha256}`;
+}
+
+function exclusionFor(repositoryPath) {
+  const segments = repositoryPath.split("/");
+  for (const exclusion of materialAdmissionPolicy.exclusions) {
+    if (exclusion.kind === "path_prefix" && repositoryPath.startsWith(exclusion.value)) return exclusion;
+    if (exclusion.kind === "path_segment" && segments.includes(exclusion.value)) return exclusion;
+  }
+  return null;
+}
+
+function classifyPath(repositoryPath) {
+  const pathFailure = normalizedPathFailure(repositoryPath);
+  if (pathFailure) return { failure: pathFailure };
+  const exclusion = exclusionFor(repositoryPath);
+  if (exclusion) return { failure: failure(exclusion.code, "material path is explicitly excluded", repositoryPath) };
+  if (!repositoryPath.endsWith(".md")) return { failure: failure("material_type_not_markdown", "only Markdown material may be admitted", repositoryPath) };
+  const route = allowedRoutes.get(repositoryPath);
+  if (!route) return { failure: failure("material_path_unapproved", "material path is absent from the sealed allow-set", repositoryPath) };
+  return { route };
+}
+
+export function createMaterialManifest(materials) {
+  if (!Array.isArray(materials)) throw new MaterialAdmissionError("material_manifest_materials_invalid", "materials must be an array");
+  const sorted = materials.map((record) => structuredClone(record)).sort((left, right) => bytewiseCompare(left.stable_ref ?? "", right.stable_ref ?? ""));
+  const base = {
+    schema_version: "2.0", record_kind: "material_manifest", stable_ref: MANIFEST_REF,
+    admission_policy_ref: materialAdmissionPolicy.stable_ref,
+    admission_policy_version_id: materialAdmissionPolicy.version_id,
+    materials: sorted,
+  };
+  return deepFreeze({ ...base, version_id: canonicalVersionId(MANIFEST_REF, base) });
+}
+
+function trackedInventory(repositoryRoot) {
+  const result = spawnSync("git", ["-C", repositoryRoot, "ls-files", "-s", "-z", "--"], { encoding: "buffer", maxBuffer: 16 * 1024 * 1024, timeout: 30_000 });
+  if (result.status !== 0) {
+    const detail = result.error?.message ?? result.stderr.toString("utf8").trim() ?? "git ls-files failed";
+    return { failure: failure("material_inventory_failed", detail) };
+  }
+  const entries = new Map();
+  for (const encoded of result.stdout.subarray(0, result.stdout.length - (result.stdout.at(-1) === 0 ? 1 : 0)).toString("utf8").split("\0").filter(Boolean)) {
+    const tab = encoded.indexOf("\t");
+    const metadata = encoded.slice(0, tab).split(" ");
+    const repositoryPath = encoded.slice(tab + 1);
+    if (tab < 0 || metadata.length !== 3) return { failure: failure("material_inventory_failed", "Git inventory entry is malformed") };
+    entries.set(repositoryPath, { mode: metadata[0], object_id: metadata[1], stage: metadata[2] });
+  }
+  return { entries };
+}
+
+function realpath(fileSystem, target) {
+  const implementation = fileSystem.realpathSync.native ?? fileSystem.realpathSync;
+  return implementation.call(fileSystem.realpathSync, target);
+}
+
+function inspectRepositoryRoot(repositoryRoot, fileSystem) {
+  const resolvedRoot = path.resolve(repositoryRoot);
+  try {
+    const stats = fileSystem.lstatSync(resolvedRoot);
+    if (!stats.isDirectory() || stats.isSymbolicLink()) return { failure: failure("material_repository_invalid", "repository root must be a non-symlink directory") };
+    return { resolvedRoot, canonicalRoot: realpath(fileSystem, resolvedRoot) };
+  } catch (error) {
+    return { failure: failure("material_repository_invalid", `repository root is unavailable: ${error.message}`) };
+  }
+}
+
+function inspectWorktreePath(rootState, repositoryPath, fileSystem) {
+  let current = rootState.resolvedRoot;
+  let targetStats;
+  try {
+    for (const component of repositoryPath.split("/")) {
+      current = path.join(current, component);
+      targetStats = fileSystem.lstatSync(current);
+      if (targetStats.isSymbolicLink()) return { failure: failure("material_path_symlink", "material path components must not be symlinks", repositoryPath) };
+    }
+    if (!targetStats.isFile()) return { failure: failure("material_path_not_regular", "material path must be a regular file", repositoryPath) };
+    const canonicalTarget = realpath(fileSystem, current);
+    const expectedTarget = path.resolve(rootState.canonicalRoot, ...repositoryPath.split("/"));
+    if (canonicalTarget !== expectedTarget || !canonicalTarget.startsWith(`${rootState.canonicalRoot}${path.sep}`)) {
+      return { failure: failure("material_path_escape", "material canonical path escapes the repository root", repositoryPath) };
+    }
+    return { target: current, canonicalTarget, dev: targetStats.dev, ino: targetStats.ino };
+  } catch (error) {
+    return { failure: failure("material_path_unavailable", `tracked material path is unavailable: ${error.message}`, repositoryPath) };
+  }
+}
+
+function validateManifestEnvelope(manifest) {
+  if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) return [failure("material_manifest_invalid", "material manifest must be an object")];
+  if (Object.keys(manifest).some((key) => !MANIFEST_KEYS.has(key))) return [failure("material_manifest_schema_invalid", "material manifest contains undeclared properties")];
+  if (manifest.schema_version !== "2.0" || manifest.record_kind !== "material_manifest" || manifest.stable_ref !== MANIFEST_REF
+    || !Array.isArray(manifest.materials) || manifest.materials.length === 0) return [failure("material_manifest_schema_invalid", "material manifest envelope is malformed")];
+  if (manifest.admission_policy_ref !== materialAdmissionPolicy.stable_ref || manifest.admission_policy_version_id !== materialAdmissionPolicy.version_id) {
+    return [failure("material_manifest_policy_mismatch", "material manifest does not bind the authoritative admission policy")];
+  }
+  if (manifest.version_id !== canonicalVersionId(MANIFEST_REF, manifest)) return [failure("material_manifest_version_invalid", "material manifest VersionID does not bind canonical manifest content")];
+  return [];
+}
+
+function validateRecordShape(record, index) {
+  const location = `/materials/${index}`;
+  if (!record || typeof record !== "object" || Array.isArray(record)) return failure("material_record_invalid", "material record must be an object", location);
+  if (Object.keys(record).some((key) => !RECORD_KEYS.has(key)) || record.schema_version !== "2.0" || record.record_kind !== "material") return failure("material_schema_invalid", "material record is not a closed v2 material", location);
+  if (!MATERIAL_REF_PATTERN.test(record.stable_ref ?? "")) return failure("material_stable_ref_invalid", "material StableRef is malformed", `${location}/stable_ref`);
+  if (!MATERIAL_VERSION_PATTERN.test(record.version_id ?? "") || !record.version_id.startsWith(`${record.stable_ref}@sha256:`)) return failure("material_version_invalid", "material VersionID is malformed or names another StableRef", `${location}/version_id`);
+  if (record.media_type !== materialAdmissionPolicy.media_type) return failure("material_media_type_invalid", "material media type must be text/markdown", `${location}/media_type`);
+  if (!HASH_PATTERN.test(record.source_sha256 ?? "")) return failure("material_hash_invalid", "material source_sha256 must be lowercase SHA-256", `${location}/source_sha256`);
+  if (!Number.isSafeInteger(record.byte_length) || record.byte_length < 0) return failure("material_length_invalid", "material byte_length must be a non-negative safe integer", `${location}/byte_length`);
+  if (!LIFECYCLES.has(record.lifecycle)) return failure("material_lifecycle_invalid", "material lifecycle is unsupported", `${location}/lifecycle`);
+  if (!DOMAINS.has(record.domain)) return failure("material_domain_invalid", "material domain is unsupported", `${location}/domain`);
+  const classified = classifyPath(record.repository_path);
+  if (classified.failure) return classified.failure;
+  if (record.stable_ref !== materialStableRefForPath(record.repository_path)) return failure("material_stable_ref_path_mismatch", "material StableRef does not derive from repository_path", `${location}/stable_ref`);
+  if (record.domain !== classified.route.domain) return failure("material_domain_route_mismatch", "material domain does not match policy", `${location}/domain`);
+  if (record.lifecycle !== classified.route.lifecycle) return failure("material_lifecycle_route_mismatch", "material lifecycle does not match policy", `${location}/lifecycle`);
+  if (record.version_id !== materialVersionIdForSource(record.stable_ref, record.source_sha256)) return failure("material_version_invalid", "material VersionID does not bind exact source SHA-256", `${location}/version_id`);
+  if (!validateRecordSchema(record)) return failure("material_schema_invalid", "material record does not satisfy the closed schema", location);
+  return null;
+}
+
+export function validateMaterialManifest({ repositoryRoot, manifest, fileSystem = fs, readFile }) {
+  const envelopeFailures = validateManifestEnvelope(manifest);
+  if (envelopeFailures.length > 0) return deepFreeze({ ok: false, failures: envelopeFailures, materials: [] });
+  const recordFailures = manifest.materials.map(validateRecordShape).filter(Boolean);
+  if (recordFailures.length > 0) return deepFreeze({ ok: false, failures: recordFailures, materials: [] });
+  if (!validateManifestSchema(manifest)) return deepFreeze({ ok: false, failures: [failure("material_manifest_schema_invalid", "manifest does not satisfy the closed schema")], materials: [] });
+
+  const refs = manifest.materials.map(({ stable_ref }) => stable_ref);
+  const paths = manifest.materials.map(({ repository_path }) => repository_path);
+  const duplicateFailures = [];
+  if (new Set(refs).size !== refs.length) duplicateFailures.push(failure("material_identity_duplicate", "material StableRefs must be unique"));
+  if (new Set(paths).size !== paths.length) duplicateFailures.push(failure("material_path_duplicate", "material paths must be unique"));
+  if (duplicateFailures.length > 0) return deepFreeze({ ok: false, failures: duplicateFailures, materials: [] });
+  if (refs.some((entry, index) => index > 0 && bytewiseCompare(refs[index - 1], entry) >= 0)) return deepFreeze({ ok: false, failures: [failure("material_manifest_order_invalid", "materials must be bytewise sorted by StableRef")], materials: [] });
+
+  const inventory = trackedInventory(repositoryRoot);
+  if (inventory.failure) return deepFreeze({ ok: false, failures: [inventory.failure], materials: [] });
+  for (const record of manifest.materials) {
+    const indexEntry = inventory.entries.get(record.repository_path);
+    if (!indexEntry) return deepFreeze({ ok: false, failures: [failure("material_path_untracked", "material path is absent from tracked Git inventory", record.repository_path)], materials: [] });
+    if (!new Set(["100644", "100755"]).has(indexEntry.mode) || indexEntry.stage !== "0") return deepFreeze({ ok: false, failures: [failure("material_git_mode_invalid", "material Git index entry must be a stage-zero regular blob", record.repository_path)], materials: [] });
+  }
+
+  const rootState = inspectRepositoryRoot(repositoryRoot, fileSystem);
+  if (rootState.failure) return deepFreeze({ ok: false, failures: [rootState.failure], materials: [] });
+  const inspections = [];
+  for (const record of manifest.materials) {
+    const inspection = inspectWorktreePath(rootState, record.repository_path, fileSystem);
+    if (inspection.failure) return deepFreeze({ ok: false, failures: [inspection.failure], materials: [] });
+    inspections.push(inspection);
+  }
+
+  const reader = readFile ?? ((descriptor) => fileSystem.readFileSync(descriptor));
+  const admitted = [];
+  for (let index = 0; index < manifest.materials.length; index += 1) {
+    const record = manifest.materials[index];
+    const inspection = inspections[index];
+    let descriptor;
+    let bytes;
+    try {
+      descriptor = fileSystem.openSync(inspection.target, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+      const descriptorStats = fileSystem.fstatSync(descriptor);
+      const currentStats = fileSystem.lstatSync(inspection.target);
+      const currentCanonical = realpath(fileSystem, inspection.target);
+      if (!descriptorStats.isFile() || currentStats.isSymbolicLink() || !currentStats.isFile()
+        || descriptorStats.dev !== inspection.dev || descriptorStats.ino !== inspection.ino
+        || currentStats.dev !== inspection.dev || currentStats.ino !== inspection.ino
+        || currentCanonical !== inspection.canonicalTarget) {
+        return deepFreeze({ ok: false, failures: [failure("material_path_race", "material path identity changed after preflight", record.repository_path)], materials: [] });
+      }
+      bytes = reader(descriptor);
+    } catch (error) {
+      const code = error?.code === "ELOOP" || error?.code === "ENOENT" ? "material_path_race" : "material_read_failed";
+      return deepFreeze({ ok: false, failures: [failure(code, `material could not be read safely: ${error.message}`, record.repository_path)], materials: [] });
+    } finally {
+      if (descriptor !== undefined) fileSystem.closeSync(descriptor);
+    }
+    if (!(bytes instanceof Uint8Array)) return deepFreeze({ ok: false, failures: [failure("material_read_invalid", "material reader must return bytes", record.repository_path)], materials: [] });
+    if (sha256(bytes) !== record.source_sha256) return deepFreeze({ ok: false, failures: [failure("material_source_hash_mismatch", "material bytes do not match source_sha256", record.repository_path)], materials: [] });
+    if (bytes.byteLength !== record.byte_length) return deepFreeze({ ok: false, failures: [failure("material_byte_length_mismatch", "material bytes do not match byte_length", record.repository_path)], materials: [] });
+    admitted.push({ ...record });
+  }
+  return deepFreeze({ ok: true, failures: [], materials: admitted });
+}
+
+export function resolveMaterialRecord({ manifest, reference }) {
+  if (!MATERIAL_REF_PATTERN.test(reference ?? "")) throw new MaterialAdmissionError("material_reference_invalid", "runtime material references must be v2 StableRefs");
+  const record = manifest?.materials?.find(({ stable_ref }) => stable_ref === reference);
+  if (!record) throw new MaterialAdmissionError("material_reference_not_found", "material StableRef is absent from the manifest");
+  return deepFreeze(structuredClone(record));
+}

package/scripts/agent-native/v2/material-cli-adapter.mjs

@@ -0,0 +1,134 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { deepFreeze } from "../canonical-json.mjs";
+import { createMaterialOperationRegistry } from "./material-operation-registry.mjs";
+
+const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../..");
+const operationForCommand = Object.freeze({
+  context: "material-context",
+  discover: "material-discover",
+  get: "material-get",
+  search: "material-search",
+});
+const optionSpecs = Object.freeze({
+  "--budget-tokens": { commands: new Set(["context"]), field: "budget_tokens", integer: true },
+  "--limit": { commands: new Set(["search"]), field: "limit", integer: true },
+  "--limit-bytes": { commands: new Set(["get"]), field: "length", integer: true },
+  "--offset": { commands: new Set(["get"]), field: "offset", integer: true },
+  "--query": { commands: new Set(["context", "search"]), field: "query" },
+  "--reference": { commands: new Set(["get"]), field: "reference" },
+});
+const requiredOptions = Object.freeze({ context: ["--query"], discover: [], get: ["--reference"], search: ["--query"] });
+const inputOrder = Object.freeze({
+  context: ["--query", "--budget-tokens"],
+  discover: [],
+  get: ["--reference", "--offset", "--limit-bytes"],
+  search: ["--query", "--limit"],
+});
+
+function issue(code, message) { return { code, message }; }
+function failed(operation, failure) { return deepFreeze({ failures: [failure], ok: false, operation }); }
+function parseInteger(value) {
+  if (!/^[0-9]+$/.test(value)) return null;
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) ? parsed : null;
+}
+
+export function parseMaterialCliArguments(args) {
+  if (!Array.isArray(args)) return failed(null, issue("argument_list_invalid", "CLI arguments must be an array"));
+  let command;
+  let help = false;
+  const values = new Map();
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index];
+    if (typeof argument !== "string") return failed(command ?? null, issue("argument_unknown", "unsupported CLI argument"));
+    if (argument === "--help") {
+      if (help) return failed(command ?? null, issue("argument_duplicate", "an option was supplied more than once"));
+      help = true;
+      continue;
+    }
+    if (argument.startsWith("--")) {
+      const spec = optionSpecs[argument];
+      if (!spec) return failed(command ?? null, issue("argument_unknown", "unknown option"));
+      if (values.has(argument)) return failed(command ?? null, issue("argument_duplicate", "an option was supplied more than once"));
+      const value = args[index + 1];
+      if (value === undefined || typeof value !== "string" || value.startsWith("--")) {
+        return failed(command ?? null, issue("argument_value_required", "an option value is required"));
+      }
+      values.set(argument, value);
+      index += 1;
+      continue;
+    }
+    if (command !== undefined) return failed(command, issue("argument_unknown", "positional operands are not supported"));
+    command = argument;
+  }
+  if (help) {
+    if (command !== undefined || values.size > 0) return failed(command ?? null, issue("argument_inapplicable", "help cannot be combined with commands or options"));
+    return deepFreeze({ command: "help", input: {}, ok: true });
+  }
+  if (command === undefined) return failed(null, issue("argument_value_required", "a command is required"));
+  if (!Object.hasOwn(operationForCommand, command)) return failed(command, issue("command_unknown", "unknown command"));
+  for (const [option, value] of values) {
+    const spec = optionSpecs[option];
+    if (!spec.commands.has(command)) return failed(command, issue("argument_inapplicable", "option is not supported by this command"));
+    if (spec.integer && parseInteger(value) === null) return failed(command, issue("argument_integer_invalid", "option value must be an unsigned decimal safe integer"));
+  }
+  if (requiredOptions[command].some((option) => !values.has(option))) {
+    return failed(command, issue("argument_value_required", "a required option is missing"));
+  }
+  const input = {};
+  for (const option of inputOrder[command]) {
+    if (!values.has(option)) continue;
+    const spec = optionSpecs[option];
+    input[spec.field] = spec.integer ? parseInteger(values.get(option)) : values.get(option);
+  }
+  return deepFreeze({ command, input, ok: true });
+}
+
+const helpResult = deepFreeze({
+  commands: [
+    { name: "discover", options: [] },
+    { name: "search", options: ["--query", "--limit"] },
+    { name: "get", options: ["--reference", "--offset", "--limit-bytes"] },
+    { name: "context", options: ["--query", "--budget-tokens"] },
+  ],
+  options: ["--query", "--reference", "--offset", "--limit-bytes", "--limit", "--budget-tokens", "--help"],
+});
+
+function packagedInventoryRunner(root) {
+  const manifestPath = path.join(root, "consumer-reference", "agent-native", "v2", "material-registry.json");
+  return () => {
+    try {
+      const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+      const stdout = Buffer.from(manifest.materials.map((record) => `100644 ${record.source_sha256} 0\t${record.repository_path}\0`).join(""), "utf8");
+      return { error: undefined, status: 0, stderr: Buffer.alloc(0), stdout };
+    } catch {
+      return { error: undefined, status: 1, stderr: Buffer.alloc(0), stdout: Buffer.alloc(0) };
+    }
+  };
+}
+
+function runtimeRegistry() {
+  const hasGitMetadata = fs.existsSync(path.join(repositoryRoot, ".git"));
+  return createMaterialOperationRegistry({
+    repositoryRoot,
+    ...(hasGitMetadata ? {} : { gitRunner: packagedInventoryRunner(repositoryRoot) }),
+  });
+}
+
+export function executeMaterialCli(args, registry = runtimeRegistry()) {
+  const parsed = parseMaterialCliArguments(args);
+  if (!parsed.ok) return parsed;
+  if (parsed.command === "help") return deepFreeze({ ok: true, operation: "help", result: helpResult });
+  if (!registry || typeof registry.invoke !== "function") return failed(parsed.command, issue("material_registry_invalid", "v2 material registry is unavailable"));
+  return registry.invoke(operationForCommand[parsed.command], parsed.input);
+}
+
+export function serializeMaterialCliReport(report) { return `${JSON.stringify(report, null, 2)}\n`; }
+
+export function runMaterialCli(args, registry) {
+  const report = executeMaterialCli(args, registry);
+  return deepFreeze({ exitCode: report.ok ? 0 : 1, output: serializeMaterialCliReport(report), report });
+}