stylegallery 0.1.0 → 0.1.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "stylegallery",
-  "version": "0.1.0",
-  "description": "A governed gallery of portable interface knowledge with a deterministic CLI and read-only MCP server.",
+  "version": "0.1.2",
+  "description": "A governed gallery of portable interface knowledge with deterministic CLIs and read-only MCP servers.",
   "type": "module",
   "homepage": "https://github.com/changeroa/StyleGallery#readme",
   "bugs": {
@@ -22,30 +22,177 @@
   "engines": {
     "node": ">=22"
   },
-  "bin": {
-    "sg": "scripts/sg.mjs",
-    "stylegallery": "scripts/sg.mjs",
-    "stylegallery-mcp": "scripts/sg-mcp.mjs"
-  },
   "files": [
     "AGENTS.md",
     "CATALOG.md",
     "DOMAINS.md",
     "GOVERNANCE.md",
     "GUIDE.md",
-    "consumer-reference/",
-    "design-engineering/",
-    "game-ui/",
-    "guides/",
+    "README.md",
+    "consumer-reference/agent-native/README.md",
+    "consumer-reference/agent-native/registry.json",
+    "consumer-reference/agent-native/schema/agent-native.schema.json",
+    "consumer-reference/agent-native/schema/epistemic.schema.json",
+    "consumer-reference/agent-native/schema/execution.schema.json",
+    "consumer-reference/agent-native/schema/identity.schema.json",
+    "consumer-reference/agent-native/schema/learning.schema.json",
+    "consumer-reference/agent-native/schema/manifest.schema.json",
+    "consumer-reference/agent-native/schema/operation.schema.json",
+    "consumer-reference/agent-native/schema/protocol-binding.schema.json",
+    "consumer-reference/agent-native/schema/retrieval.schema.json",
+    "consumer-reference/agent-native/v2/admission-policy.json",
+    "consumer-reference/agent-native/v2/material-registry.json",
+    "consumer-reference/agent-native/v2/schema/admission-policy.schema.json",
+    "consumer-reference/agent-native/v2/schema/material-manifest.schema.json",
+    "consumer-reference/agent-native/v2/schema/material-record.schema.json",
+    "consumer-reference/contract.md",
+    "consumer-reference/index.md",
+    "design-engineering/index.md",
+    "design-engineering/reference-profiles/governed-local/editorial/profile.json",
+    "design-engineering/reference-profiles/governed-local/index.md",
+    "design-engineering/reference-profiles/index.md",
+    "game-ui/index.md",
+    "guides/decision-tree.md",
+    "guides/documentation-mode-taxonomy.md",
+    "guides/layout-brief.md",
+    "guides/vocabulary.md",
+    "guides/webpage-generation-workflow.md",
     "index.md",
-    "layout/",
-    "motion/",
-    "patterns/",
-    "platform-guides/",
-    "quality/",
-    "recipes/",
-    "scripts/"
+    "layout/index.md",
+    "log.md",
+    "motion/index.md",
+    "patterns/centering/center.md",
+    "patterns/centering/index.md",
+    "patterns/centering/super-center.md",
+    "patterns/containment/box.md",
+    "patterns/containment/clamped-card.md",
+    "patterns/containment/content-limiter.md",
+    "patterns/containment/fluid-styles.md",
+    "patterns/containment/index.md",
+    "patterns/grid-repetition/card-grid.md",
+    "patterns/grid-repetition/columns.md",
+    "patterns/grid-repetition/dense-grid.md",
+    "patterns/grid-repetition/grid-wrapper.md",
+    "patterns/grid-repetition/index.md",
+    "patterns/grid-repetition/masonry-approx.md",
+    "patterns/grid-repetition/page-grid.md",
+    "patterns/grid-repetition/ram-grid.md",
+    "patterns/grid-repetition/twelve-span-grid.md",
+    "patterns/in-line-grouping/badge-list.md",
+    "patterns/in-line-grouping/breadcrumb.md",
+    "patterns/in-line-grouping/cluster.md",
+    "patterns/in-line-grouping/deconstructed-pancake.md",
+    "patterns/in-line-grouping/index.md",
+    "patterns/in-line-grouping/pagination.md",
+    "patterns/in-line-grouping/reel.md",
+    "patterns/in-line-grouping/split-nav.md",
+    "patterns/in-line-grouping/tab-strip.md",
+    "patterns/in-line-grouping/wrap-row.md",
+    "patterns/index.md",
+    "patterns/media-fit/frame.md",
+    "patterns/media-fit/icon-frame.md",
+    "patterns/media-fit/index.md",
+    "patterns/overlay-exception/imposter.md",
+    "patterns/overlay-exception/index.md",
+    "patterns/overlay-exception/overlay-stack.md",
+    "patterns/split-sidebar/index.md",
+    "patterns/split-sidebar/list-detail.md",
+    "patterns/split-sidebar/main-with-rail.md",
+    "patterns/split-sidebar/media-object.md",
+    "patterns/split-sidebar/sidebar.md",
+    "patterns/split-sidebar/split-screen.md",
+    "patterns/split-sidebar/sticky-aside.md",
+    "patterns/split-sidebar/supporting-pane.md",
+    "patterns/split-sidebar/switcher.md",
+    "patterns/stacking/feed.md",
+    "patterns/stacking/index.md",
+    "patterns/stacking/line-up.md",
+    "patterns/stacking/stack.md",
+    "patterns/stacking/step-nav.md",
+    "patterns/viewport-shell/cover.md",
+    "patterns/viewport-shell/fixed-sidenav-shell.md",
+    "patterns/viewport-shell/holy-grail.md",
+    "patterns/viewport-shell/index.md",
+    "patterns/viewport-shell/panel-layout.md",
+    "patterns/viewport-shell/scroll-body-shell.md",
+    "patterns/viewport-shell/sticky-footer.md",
+    "patterns/viewport-shell/sticky-header.md",
+    "platform-guides/index.md",
+    "quality/claim-records/index.md",
+    "quality/claim-records/samples.md",
+    "quality/claim-records/stylegallery-multidomain-scope.md",
+    "quality/claims.md",
+    "quality/evidence/accessibility.md",
+    "quality/evidence/consumer-migration.md",
+    "quality/evidence/design-rationale.md",
+    "quality/evidence/executable-evidence.md",
+    "quality/evidence/families.md",
+    "quality/evidence/hci-evaluation.md",
+    "quality/evidence/index.md",
+    "quality/evidence/pattern-contract-audit.md",
+    "quality/evidence/search-metadata-polyhierarchy.md",
+    "quality/evidence/sources.md",
+    "quality/evidence/tokens.md",
+    "quality/evidence/visual-qa.md",
+    "quality/gates/accessibility-evidence.md",
+    "quality/gates/consumer-migration-evidence.md",
+    "quality/gates/design-claim.md",
+    "quality/gates/harmony-evaluation.md",
+    "quality/gates/index.md",
+    "quality/gates/layout.md",
+    "quality/gates/rationale.md",
+    "quality/gates/visual-evidence.md",
+    "quality/index.md",
+    "quality/principles.md",
+    "recipes/article-page.md",
+    "recipes/command-surface.md",
+    "recipes/dashboard.md",
+    "recipes/form-flow.md",
+    "recipes/homepage.md",
+    "recipes/index.md",
+    "recipes/list-detail.md",
+    "recipes/primitive-to-recipe-matrix.md",
+    "recipes/saas-settings.md",
+    "scripts/agent-native/a2a-projection.mjs",
+    "scripts/agent-native/agui-projection.mjs",
+    "scripts/agent-native/canonical-json.mjs",
+    "scripts/agent-native/cli-adapter.mjs",
+    "scripts/agent-native/execution.mjs",
+    "scripts/agent-native/fixture.mjs",
+    "scripts/agent-native/identity.mjs",
+    "scripts/agent-native/knowledge.mjs",
+    "scripts/agent-native/learning-records.mjs",
+    "scripts/agent-native/learning.mjs",
+    "scripts/agent-native/mcp-adapter.mjs",
+    "scripts/agent-native/queries.mjs",
+    "scripts/agent-native/registry.mjs",
+    "scripts/agent-native/retrieval.mjs",
+    "scripts/agent-native/self-description.mjs",
+    "scripts/agent-native/v2/experimental-extension-registry.mjs",
+    "scripts/agent-native/v2/extensions/a2a-projection.mjs",
+    "scripts/agent-native/v2/extensions/agui-projection.mjs",
+    "scripts/agent-native/v2/material-admission.mjs",
+    "scripts/agent-native/v2/material-cli-adapter.mjs",
+    "scripts/agent-native/v2/material-context.mjs",
+    "scripts/agent-native/v2/material-identity.mjs",
+    "scripts/agent-native/v2/material-mcp-adapter.mjs",
+    "scripts/agent-native/v2/material-operation-registry.mjs",
+    "scripts/agent-native/v2/material-queries.mjs",
+    "scripts/agent-native/v2/material-registry.mjs",
+    "scripts/sg-material-mcp.mjs",
+    "scripts/sg-material.mjs",
+    "scripts/sg-mcp.mjs",
+    "scripts/sg.mjs",
+    "scripts/strict-json.mjs"
   ],
+  "bin": {
+    "sg": "scripts/sg.mjs",
+    "sg-material": "scripts/sg-material.mjs",
+    "stylegallery": "scripts/sg.mjs",
+    "stylegallery-material": "scripts/sg-material.mjs",
+    "stylegallery-material-mcp": "scripts/sg-material-mcp.mjs",
+    "stylegallery-mcp": "scripts/sg-mcp.mjs"
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -55,13 +202,25 @@
     "create:component-state-session": "node scripts/create-component-state-session.mjs",
     "test": "node scripts/test-reference-adapters.mjs --json",
     "test:consumer-conformance": "playwright test tests/consumer-conformance.spec.mjs",
+    "test:homepage:cdp": "node examples/stylegallery-homepage/qa.mjs",
+    "test:consumer-conformance:matrix": "node scripts/agent-native/v2/test-consumer-conformance-matrix-comparator.mjs",
+    "test:consumer-conformance:matrix:execute": "node scripts/agent-native/v2/test-consumer-conformance-matrix-comparator.mjs --execute",
     "test:component-state": "node scripts/test-component-state-source-contract.mjs && node scripts/test-validate-component-state.mjs --json && node scripts/test-validate-component-state-artifacts.mjs && node scripts/test-generate-consumer-reference-evidence.mjs --json",
     "test:component-state:runtime": "playwright test tests/component-state-evidence.spec.mjs --project=chromium",
     "test:component-state:runtime-negative": "node scripts/test-component-state-sentinel.mjs",
     "test:sentinel": "playwright test tests/consumer-reference-sentinels.spec.mjs --project=chromium",
+    "test:source-inventory": "node --test scripts/test-repository-source-inventory.mjs",
+    "test:json-schema-formats": "node --test scripts/test-json-schema-formats.mjs",
+    "generate:material": "node scripts/agent-native/v2/generate-material-registry.mjs",
+    "validate:material": "node scripts/agent-native/v2/validate-material-registry.mjs",
+    "test:material": "node scripts/agent-native/v2/test-material-admission.mjs && node scripts/agent-native/v2/test-material-registry.mjs && node scripts/agent-native/v2/test-material-query.mjs && node scripts/agent-native/v2/test-material-context.mjs && node scripts/agent-native/v2/test-sg-material-cli.mjs && node scripts/agent-native/v2/test-material-mcp.mjs && node scripts/agent-native/v2/test-material-mcp-stdio.mjs && node scripts/agent-native/v2/test-sg-material-package.mjs",
+    "test:lifecycle-dispositions": "node scripts/test-lifecycle-disposition.mjs",
+    "validate:lifecycle-dispositions": "node scripts/validate-lifecycle-disposition.mjs --json",
     "sg": "node scripts/sg.mjs",
+    "sg:material": "node scripts/sg-material.mjs",
+    "sg:material:mcp": "node scripts/sg-material-mcp.mjs",
     "sg:mcp": "node scripts/sg-mcp.mjs",
-    "test:agent-native": "node scripts/test-agent-knowledge-kernel.mjs --json && node scripts/test-agent-execution-kernel.mjs --json && node scripts/test-agent-execution-safety.mjs --json && node scripts/test-agent-events.mjs --json && node scripts/test-agent-learning.mjs --json && node scripts/test-agent-native-schemas.mjs --json && node scripts/test-sg-cli.mjs --json && node scripts/test-agent-conformance-receipt.mjs --json && node scripts/test-agent-mcp.mjs --json && node scripts/test-agent-registry-mcp-integrity.mjs --json && node scripts/test-agent-registry-mutations.mjs --json && node scripts/test-agent-adapter-conformance.mjs --json && node scripts/test-agent-projections.mjs --json",
+    "test:agent-native": "node scripts/test-agent-knowledge-kernel.mjs --json && node scripts/test-agent-execution-kernel.mjs --json && node scripts/test-agent-execution-safety.mjs --json && node scripts/test-agent-events.mjs --json && node scripts/test-agent-learning.mjs --json && node scripts/test-agent-native-schemas.mjs --json && node scripts/test-sg-cli.mjs --json && node scripts/test-agent-conformance-receipt.mjs --json && node scripts/test-agent-mcp.mjs --json && node scripts/test-agent-registry-mcp-integrity.mjs --json && node scripts/test-agent-registry-mutations.mjs --json && node scripts/test-agent-adapter-conformance.mjs --json && node scripts/agent-native/v2/test-agent-extension-boundary.mjs && node scripts/test-agent-projections.mjs --json && node scripts/agent-native/v2/test-agent-v1-compatibility.mjs",
     "validate": "node scripts/validate-reference-artifacts.mjs --manifest consumer-reference/generated/manifest.json --json",
     "validate:component-state": "node scripts/validate-component-state.mjs --json && node scripts/generate-consumer-reference-evidence.mjs --check --json"
   },
@@ -69,10 +228,12 @@
     "@axe-core/playwright": "4.12.1",
     "@playwright/test": "1.61.0",
     "ajv": "8.20.0",
-    "ajv-formats": "3.0.1",
-    "style-dictionary": "5.5.0"
+    "ajv-formats": "3.0.1"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.29.0"
+    "@chenglou/pretext": "0.0.8",
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "style-dictionary": "5.5.0",
+    "zod": "4.4.3"
   }
 }

package/scripts/agent-native/v2/experimental-extension-registry.mjs

@@ -0,0 +1,143 @@
+import { types as utilTypes } from "node:util";
+
+import { A2A_EXPERIMENTAL_EXTENSION } from "./extensions/a2a-projection.mjs";
+import { AG_UI_EXPERIMENTAL_EXTENSION } from "./extensions/agui-projection.mjs";
+
+const SUPPORTED = Object.freeze({ a2a: "1.0", "ag-ui": "0.0.57" });
+const CANONICAL = new Map([
+  ["a2a\u00001.0", A2A_EXPERIMENTAL_EXTENSION],
+  ["ag-ui\u00000.0.57", AG_UI_EXPERIMENTAL_EXTENSION],
+]);
+const SENSITIVE_FIELDS = new Set(["body", "prose", "repository_path", "repository_root", "source", "source_body", "source_path"]);
+const SENSITIVE_INPUT_FIELDS = new Set([...SENSITIVE_FIELDS, "path"]);
+const DESCRIPTOR_KEYS = new Set(["operations", "protocol", "version"]);
+const REQUEST_KEYS = new Set(["input", "operation", "protocol", "version"]);
+
+export class ExperimentalExtensionError extends TypeError {
+  constructor(code, message) {
+    super(message);
+    this.name = "ExperimentalExtensionError";
+    this.code = code;
+  }
+}
+
+function fail(code, message) {
+  throw new ExperimentalExtensionError(code, message);
+}
+function unsafe() {
+  fail("experimental_extension_input_unsafe", "experimental extension input must contain only own plain data");
+}
+function descriptorsOf(value, allowedKeys) {
+  if (!value || typeof value !== "object" || Array.isArray(value) || utilTypes.isProxy(value)) unsafe();
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) unsafe();
+  const keys = Reflect.ownKeys(value);
+  if (keys.some((key) => typeof key !== "string" || (allowedKeys && !allowedKeys.has(key)))) unsafe();
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  if (keys.some((key) => !Object.hasOwn(descriptors[key], "value") || descriptors[key].enumerable !== true)) unsafe();
+  return descriptors;
+}
+function snapshotJson(value, seen = new WeakSet()) {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return value;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) unsafe();
+    return value;
+  }
+  if (!value || typeof value !== "object" || utilTypes.isProxy(value) || seen.has(value)) unsafe();
+  const array = Array.isArray(value);
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== (array ? Array.prototype : Object.prototype) && prototype !== null) unsafe();
+  const keys = Reflect.ownKeys(value);
+  if (keys.some((key) => typeof key !== "string" || key === "__proto__" || key === "prototype" || key === "constructor")) unsafe();
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  if (keys.some((key) => !Object.hasOwn(descriptors[key], "value") || (descriptors[key].enumerable !== true && !(array && key === "length")))) unsafe();
+  if (array && keys.some((key) => key !== "length" && (!/^(0|[1-9][0-9]*)$/.test(key) || Number(key) >= value.length))) unsafe();
+  seen.add(value);
+  const copy = array ? [] : {};
+  for (const key of keys) {
+    if (array && key === "length") continue;
+    copy[key] = snapshotJson(descriptors[key].value, seen);
+  }
+  seen.delete(value);
+  return copy;
+}
+function extensionKey(protocol, version) {
+  return `${protocol}\u0000${version}`;
+}
+function deepFreeze(value) {
+  if (!value || typeof value !== "object" || Object.isFrozen(value)) return value;
+  for (const child of Object.values(value)) deepFreeze(child);
+  return Object.freeze(value);
+}
+function assertNoSensitiveFields(value, forbidden = SENSITIVE_FIELDS) {
+  if (!value || typeof value !== "object") return;
+  for (const [key, child] of Object.entries(value)) {
+    if (forbidden.has(key.toLowerCase())) {
+      fail("experimental_extension_sensitive_field_forbidden", "sensitive path or body fields cannot cross the experimental extension boundary");
+    }
+    assertNoSensitiveFields(child, forbidden);
+  }
+}
+function validateProtocol(protocol, version) {
+  if (typeof protocol !== "string" || !Object.hasOwn(SUPPORTED, protocol)) {
+    fail("experimental_extension_protocol_unknown", "experimental extension protocol is not supported");
+  }
+  if (typeof version !== "string" || SUPPORTED[protocol] !== version) {
+    fail("experimental_extension_version_unknown", "experimental extension version is not supported");
+  }
+}
+function snapshotDescriptor(descriptor) {
+  const fields = descriptorsOf(descriptor, DESCRIPTOR_KEYS);
+  if (!fields.protocol || !fields.version || !fields.operations) {
+    fail("experimental_extension_registration_invalid", "protocol, version, and operations are required");
+  }
+  const protocol = fields.protocol.value;
+  const version = fields.version.value;
+  validateProtocol(protocol, version);
+  const operationFields = descriptorsOf(fields.operations.value);
+  const names = Object.keys(operationFields).sort();
+  if (names.length === 0 || names.some((name) => name.length === 0 || typeof operationFields[name].value !== "function")) {
+    fail("experimental_extension_registration_invalid", "operations must be a non-empty own function map");
+  }
+  const canonical = CANONICAL.get(extensionKey(protocol, version));
+  const canonicalNames = Object.keys(canonical.operations).sort();
+  if (JSON.stringify(names) !== JSON.stringify(canonicalNames)) {
+    fail("experimental_extension_catalog_invalid", "experimental extension operation catalog does not match the governed catalog");
+  }
+  if (names.some((name) => operationFields[name].value !== canonical.operations[name])) {
+    fail("experimental_extension_implementation_invalid", "experimental extension implementation does not match the governed projection");
+  }
+  return { names, operations: new Map(names.map((name) => [name, operationFields[name].value])), protocol, version };
+}
+
+/** Create an empty registry. Protocol extensions are never imported or registered by v1 core. */
+export function createExperimentalExtensionRegistry() {
+  const extensions = new Map();
+  const register = (descriptor) => {
+    const snapshot = snapshotDescriptor(descriptor);
+    const key = extensionKey(snapshot.protocol, snapshot.version);
+    if (extensions.has(key)) fail("experimental_extension_duplicate", "experimental extension is already registered");
+    extensions.set(key, snapshot);
+    return Object.freeze({ operations: Object.freeze([...snapshot.names]), protocol: snapshot.protocol, version: snapshot.version });
+  };
+  const list = () => Object.freeze([...extensions.values()]
+    .map(({ names, protocol, version }) => Object.freeze({ operations: Object.freeze([...names]), protocol, version }))
+    .sort((left, right) => left.protocol.localeCompare(right.protocol) || left.version.localeCompare(right.version)));
+  const project = (request) => {
+    const fields = descriptorsOf(request, REQUEST_KEYS);
+    const snapshot = snapshotJson(Object.fromEntries(Object.entries(fields).map(([key, descriptor]) => [key, descriptor.value])));
+    validateProtocol(snapshot.protocol, snapshot.version);
+    assertNoSensitiveFields(snapshot.input, SENSITIVE_INPUT_FIELDS);
+    const extension = extensions.get(extensionKey(snapshot.protocol, snapshot.version));
+    if (!extension) fail("experimental_extension_protocol_unknown", "experimental extension is not registered");
+    if (typeof snapshot.operation !== "string" || !extension.operations.has(snapshot.operation)) {
+      fail("experimental_extension_operation_unknown", "experimental extension operation is not registered");
+    }
+    const result = snapshotJson(extension.operations.get(snapshot.operation)(snapshot.input));
+    assertNoSensitiveFields(result);
+    return deepFreeze(result);
+  };
+  return Object.freeze({ list, project, register });
+}
+
+export const experimentalExtensionVersions = SUPPORTED;

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

@@ -0,0 +1,264 @@
+import { cloneAndFreeze, hashCanonical } from "../../canonical-json.mjs";
+
+const STATE_MAP = Object.freeze({
+  PENDING: "submitted", CREATED: "submitted", QUEUED: "submitted", SUBMITTED: "submitted",
+  RUNNING: "working", STARTED: "working", IN_PROGRESS: "working", WORKING: "working",
+  COMPLETED: "completed", SUCCEEDED: "completed", SUCCESS: "completed", DONE: "completed",
+  FAILED: "failed", ERROR: "failed", ERRORED: "failed",
+  CANCELED: "canceled", CANCELLED: "canceled", ABORTED: "canceled",
+  REJECTED: "rejected", AUTH_REQUIRED: "auth-required", AUTHENTICATION_REQUIRED: "auth-required",
+});
+
+const TERMINAL_STATES = new Set(["completed", "failed", "canceled", "rejected", "auth-required"]);
+
+export class A2AProjectionError extends TypeError {
+  constructor(code, message, path = "") {
+    super(message);
+    this.name = "A2AProjectionError";
+    this.code = code;
+    if (path) this.path = path;
+  }
+}
+
+function fail(code, message, path) {
+  throw new A2AProjectionError(code, message, path);
+}
+
+function object(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function pick(value, ...keys) {
+  if (!object(value)) return undefined;
+  for (const key of keys) if (Object.hasOwn(value, key) && value[key] !== undefined) return value[key];
+  return undefined;
+}
+
+function copy(value) {
+  return value === undefined ? undefined : structuredClone(value);
+}
+
+function freeze(value) {
+  return cloneAndFreeze(value);
+}
+
+function digest(value) {
+  return hashCanonical(value).slice("sha256:".length);
+}
+
+function idOf(value, ...keys) {
+  const id = pick(value, ...keys, "stableRef", "stable_ref", "id");
+  return typeof id === "string" && id.length > 0 ? id : undefined;
+}
+
+function domainTaskId(source, task) {
+  const explicit = idOf(source, "domainTaskId", "domain_task_id");
+  const taskRef = idOf(task, "taskId", "task_id", "stableRef", "stable_ref");
+  const generic = !pick(source, "domainTask", "domain_task") ? idOf(source, "taskId", "task_id") : undefined;
+  return explicit
+    ?? taskRef
+    ?? generic
+    ?? `sg:task/a2a-${digest({ task, message: pick(source, "message") }).slice(0, 20)}`;
+}
+
+function domainRunId(source, run, taskId) {
+  const explicit = idOf(source, "domainRunId", "domain_run_id");
+  const runRef = idOf(run, "runId", "run_id", "stableRef", "stable_ref");
+  const generic = !pick(source, "domainRun", "domain_run") ? idOf(source, "runId", "run_id") : undefined;
+  return explicit
+    ?? runRef
+    ?? generic
+    ?? `sg:run/a2a-${digest({ run, taskId }).slice(0, 20)}`;
+}
+
+function protocolIds(source, task, binding, taskId, runId) {
+  const protocolTaskId = pick(source, "protocolTaskId", "protocol_task_id", "a2aTaskId", "a2a_task_id")
+    ?? pick(binding, "protocolTaskId", "protocol_task_id", "a2aTaskId", "a2a_task_id")
+    ?? pick(task, "protocolTaskId", "protocol_task_id", "a2aTaskId", "a2a_task_id")
+    ?? `a2a-task-${digest({ taskId, runId, message: pick(source, "message"), binding }).slice(0, 24)}`;
+  const protocolContextId = pick(source, "protocolContextId", "protocol_context_id", "a2aContextId", "a2a_context_id")
+    ?? pick(binding, "protocolContextId", "protocol_context_id", "a2aContextId", "a2a_context_id")
+    ?? pick(task, "contextId", "context_id")
+    ?? `a2a-context-${digest({ taskId, runId }).slice(0, 24)}`;
+  if (protocolTaskId === taskId || protocolTaskId === runId) fail("protocol_task_id_conflict", "A2A task ID must not equal a domain Task or Run ID", "protocolTaskId");
+  if (protocolContextId === taskId || protocolContextId === runId || protocolContextId === protocolTaskId) fail("protocol_context_id_conflict", "A2A context ID must remain distinct from domain and task IDs", "protocolContextId");
+  return { protocolTaskId: String(protocolTaskId), protocolContextId: String(protocolContextId) };
+}
+
+function makeBinding(binding, taskId, runId, protocolTaskId, protocolContextId) {
+  const supplied = object(binding) ? copy(binding) : {};
+  const bindingId = pick(supplied, "bindingId", "binding_id", "protocolBindingId", "protocol_binding_id")
+    ?? `sg:binding/a2a-${digest({ taskId, runId, protocolTaskId, protocolContextId }).slice(0, 24)}`;
+  if (typeof bindingId !== "string" || bindingId.length === 0) fail("protocol_binding_required", "ProtocolBinding requires a non-empty binding ID", "protocolBindingId");
+  if (bindingId === taskId || bindingId === runId || bindingId === protocolTaskId || bindingId === protocolContextId) fail("protocol_binding_id_conflict", "ProtocolBinding ID must remain distinct from every correlated ID", "protocolBindingId");
+  return freeze({
+    ...supplied,
+    bindingId,
+    domainRunId: runId,
+    domainTaskId: taskId,
+    protocol: "a2a",
+    protocolBindingId: bindingId,
+    protocolContextId,
+    protocolTaskId,
+    runId,
+    taskId,
+  });
+}
+
+function taskFrom(input) {
+  const source = object(input) ? input : {};
+  const task = object(source.task) ? source.task : source;
+  return object(task.task) && !pick(task, "status", "id", "contextId") ? task.task : task;
+}
+
+function bindingFrom(input, task) {
+  return pick(input, "protocolBinding", "protocol_binding", "binding")
+    ?? pick(task, "protocolBinding", "protocol_binding", "binding")
+    ?? {};
+}
+
+function domainState(input, task) {
+  const source = object(input) ? input : {};
+  const domainTask = pick(source, "domainTask", "domain_task");
+  return pick(domainTask, "state", "status", "taskState", "task_state")
+    ?? pick(task, "domainState", "domain_state")
+    ?? pick(task, "state", "taskState", "task_state")
+    ?? pick(pick(task, "status"), "state", "status")
+    ?? "UNKNOWN";
+}
+
+function taskStatus(task, state) {
+  const status = object(pick(task, "status")) ? copy(task.status) : {};
+  return { ...status, state };
+}
+
+function responseFor(task) {
+  const { protocolBinding: _binding, ...nested } = task;
+  return freeze({ ...task, task: nested });
+}
+
+function projectTask(input, state, mode = "project") {
+  const source = object(input) ? input : {};
+  const task = taskFrom(source);
+  const domainTask = object(pick(source, "domainTask", "domain_task")) ? pick(source, "domainTask", "domain_task") : task;
+  const run = pick(source, "run", "domainRun", "domain_run");
+  const taskId = domainTaskId(source, domainTask);
+  const runId = domainRunId(source, run, taskId);
+  const suppliedBinding = bindingFrom(source, task);
+  const { protocolTaskId, protocolContextId } = protocolIds(source, task, suppliedBinding, taskId, runId);
+  const binding = makeBinding(suppliedBinding, taskId, runId, protocolTaskId, protocolContextId);
+  const requestedTaskId = pick(source, "taskId", "task_id");
+  const existingProtocolId = pick(task, "id", "protocolTaskId", "protocol_task_id")
+    ?? (object(pick(task, "status")) ? pick(task, "taskId", "task_id") : undefined);
+  const currentProtocolId = mode === "send" ? protocolTaskId : existingProtocolId ?? protocolTaskId;
+  if (requestedTaskId !== undefined && requestedTaskId !== currentProtocolId && requestedTaskId !== protocolTaskId) fail("protocol_task_mismatch", "requested A2A task ID does not match the correlated task", "taskId");
+  const message = pick(source, "message");
+  const history = Array.isArray(pick(task, "history")) ? copy(task.history) : (message ? [copy(message)] : []);
+  const artifacts = Array.isArray(pick(task, "artifacts")) ? copy(task.artifacts) : [];
+  const projected = {
+    artifacts,
+    contextId: protocolContextId,
+    history,
+    id: currentProtocolId,
+    kind: "task",
+    metadata: {
+      ...(object(pick(task, "metadata")) ? copy(task.metadata) : {}),
+      stylegallery: { domainRunId: runId, domainTaskId: taskId, protocolBindingId: binding.protocolBindingId },
+    },
+    protocolBinding: binding,
+    status: taskStatus(task, state),
+  };
+  if (mode === "send") projected.history = message ? [copy(message)] : history;
+  return freeze(projected);
+}
+
+/** Map every domain lifecycle state to an official A2A TaskState value. */
+export function mapTaskState(value) {
+  const raw = typeof value === "string" ? value : pick(value, "state", "status", "taskState", "task_state");
+  const normalized = String(raw ?? "UNKNOWN").trim().toUpperCase().replaceAll("-", "_").replaceAll(" ", "_");
+  return STATE_MAP[normalized] ?? "unknown";
+}
+
+/** Return the deterministic, v1-shaped Agent Card for StyleGallery. */
+export function createAgentCard(input = {}) {
+  const source = object(input) ? input : {};
+  const skills = [
+    ["discover", "Discover StyleGallery capabilities and immutable manifest."],
+    ["resolve", "Resolve a StableRef or VersionID to its immutable object."],
+    ["claims", "Inspect claims, evidence, validation, and governance disposition."],
+    ["context", "Build a bounded retrieval context package with provenance."],
+    ["ops", "List read-only operation specifications and schemas."],
+    ["retrieve", "Retrieve ranked governed knowledge without mutation."],
+  ].map(([id, description]) => ({ description, examples: [], id, inputModes: ["text", "data"], name: id, outputModes: ["text", "data"], tags: ["stylegallery", "knowledge"] }));
+  return freeze({
+    capabilities: { pushNotifications: false, stateTransitionHistory: true, streaming: false },
+    defaultInputModes: ["text", "data"],
+    defaultOutputModes: ["text", "data"],
+    description: typeof source.description === "string" ? source.description : "Evidence-preserving, agent-native StyleGallery knowledge operations.",
+    name: typeof source.name === "string" ? source.name : "StyleGallery Agent",
+    protocolVersion: "1.0",
+    skills,
+    supportsAuthenticatedExtendedCard: false,
+    url: typeof source.url === "string" ? source.url : "https://stylegallery.local/agent",
+    version: typeof source.version === "string" ? source.version : "1.0.0",
+  });
+}
+
+/** Project an A2A SendMessage request into a new submitted protocol task. */
+export function sendMessage(input) {
+  const source = object(input) ? input : fail("send_message_input_required", "sendMessage expects an object");
+  const message = pick(source, "message");
+  if (!object(message)) fail("message_required", "SendMessage requires a message object", "message");
+  const task = projectTask({ ...source, message }, "submitted", "send");
+  return responseFor(task);
+}
+
+/** Project current domain Task/Run state while preserving the A2A task ID. */
+export function getTask(input) {
+  const source = object(input) ? input : fail("get_task_input_required", "getTask expects an object");
+  const task = taskFrom(source);
+  const taskId = pick(source, "taskId", "task_id");
+  if (taskId === undefined && !idOf(task, "id", "taskId", "task_id", "protocolTaskId", "protocol_task_id")) fail("protocol_task_required", "GetTask requires an A2A task ID", "taskId");
+  const state = mapTaskState(domainState(source, task));
+  const projected = projectTask(source, state);
+  return responseFor(projected);
+}
+
+/** Request cancellation; terminal non-canceled states reject invalid transitions. */
+export function cancelTask(input) {
+  const source = object(input) ? input : fail("cancel_task_input_required", "cancelTask expects an object");
+  const task = taskFrom(source);
+  const current = mapTaskState(domainState(source, task));
+  if (TERMINAL_STATES.has(current) && current !== "canceled") fail("cancellation_not_allowed", `cannot cancel a ${current} A2A task`, "task");
+  if (current === "unknown") fail("invalid_task_transition", "cannot cancel an unknown A2A task state", "task");
+  const projected = projectTask(source, "canceled");
+  return responseFor(projected);
+}
+
+export const buildAgentCard = createAgentCard;
+export const projectAgentCard = createAgentCard;
+export const agentCard = createAgentCard;
+export const projectSendMessage = sendMessage;
+export const handleSendMessage = sendMessage;
+export const projectGetTask = getTask;
+export const handleGetTask = getTask;
+export const projectCancelTask = cancelTask;
+export const handleCancelTask = cancelTask;
+export const projectTaskState = mapTaskState;
+export const toA2ATaskState = mapTaskState;
+
+export const A2A_EXPERIMENTAL_EXTENSION = Object.freeze({
+  protocol: "a2a",
+  version: "1.0",
+  operations: Object.freeze({
+    "agent-card.create": createAgentCard,
+    "message.send": sendMessage,
+    "task.cancel": cancelTask,
+    "task.get": getTask,
+    "task.state": mapTaskState,
+  }),
+});
+
+export function registerA2AExtension(registry) {
+  return registry.register(A2A_EXPERIMENTAL_EXTENSION);
+}