stylegallery 0.1.0

package/scripts/agent-native/learning-records.mjs

@@ -0,0 +1,244 @@
+import { deepFreeze } from "./canonical-json.mjs";
+import { createStableRef, createVersionId, parseStableRef, parseVersionId } from "./identity.mjs";
+
+const CONTROL_KEYS = new Set([
+  "record_kind", "schema_version", "stable_ref", "stableRef", "version_id", "versionId",
+]);
+const PASSING = new Set(["PASS", "PASSED", "VALID", "VALIDATED", "OK"]);
+
+export class LearningError extends TypeError {
+  constructor(code, message, path = "") {
+    super(message);
+    this.name = "LearningError";
+    this.code = code;
+    if (path) this.path = path;
+  }
+}
+
+export function failLearning(code, message, path = "") {
+  throw new LearningError(code, message, path);
+}
+
+export function own(value, ...keys) {
+  if (!value || typeof value !== "object") return undefined;
+  for (const key of keys) if (Object.hasOwn(value, key)) return value[key];
+  return undefined;
+}
+
+export function learningObject(value, path) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    failLearning("learning_object_required", `${path} expects an object`, path);
+  }
+  return value;
+}
+
+export function copyLearning(value) {
+  if (value === undefined || value === null || typeof value !== "object") return value;
+  if (Array.isArray(value)) return value.map((item) => (item === undefined ? null : copyLearning(item)));
+  return Object.fromEntries(
+    Object.entries(value)
+      .filter(([, item]) => item !== undefined)
+      .map(([key, item]) => [key, copyLearning(item)]),
+  );
+}
+
+export function compactLearning(fields) {
+  return Object.fromEntries(Object.entries(fields).filter(([, value]) => value !== undefined));
+}
+
+export function textLearning(value, path) {
+  if (typeof value !== "string" || value.trim() === "") {
+    failLearning("learning_text_required", `${path} must be a non-empty string`, path);
+  }
+  return value;
+}
+
+export function stableLearningRef(value, path, fallback) {
+  try {
+    return createStableRef(value ?? fallback);
+  } catch (error) {
+    failLearning("learning_stable_ref_invalid", error instanceof Error ? error.message : String(error), path);
+  }
+}
+
+function canonicalFields(source) {
+  return Object.fromEntries(
+    Object.entries(source)
+      .filter(([key, value]) => !CONTROL_KEYS.has(key) && value !== undefined)
+      .map(([key, value]) => [key, copyLearning(value)]),
+  );
+}
+
+export function makeLearningRecord(input, stableRef, recordKind, fields) {
+  const source = learningObject(input, recordKind);
+  if (source.record_kind !== undefined && source.record_kind !== recordKind) {
+    failLearning("learning_record_kind_invalid", `${recordKind} cannot be created from ${source.record_kind}`, "record_kind");
+  }
+  if (source.schema_version !== undefined && source.schema_version !== "1.0") {
+    failLearning("learning_schema_version_invalid", "learning records require schema_version 1.0", "schema_version");
+  }
+  const stable_ref = stableLearningRef(stableRef, "stable_ref");
+  const payload = {
+    schema_version: "1.0",
+    record_kind: recordKind,
+    stable_ref,
+    ...Object.fromEntries(Object.entries(fields).filter(([, value]) => value !== undefined)),
+  };
+  const version_id = createVersionId({ stable_ref, payload });
+  const supplied = own(source, "version_id", "versionId");
+  if (supplied !== undefined && supplied !== version_id) {
+    failLearning("learning_version_mismatch", "version_id does not match immutable content", "version_id");
+  }
+  return deepFreeze({ ...copyLearning(payload), version_id });
+}
+
+export function assertLearningRecord(value, recordKind, path = recordKind) {
+  const source = learningObject(value, path);
+  if (Object.hasOwn(source, "stableRef") || Object.hasOwn(source, "versionId")) {
+    failLearning("learning_record_alias_forbidden", `${path} must use canonical identity keys`, path);
+  }
+  if (source.record_kind !== recordKind) {
+    failLearning("learning_record_kind_invalid", `${path} must be ${recordKind}`, `${path}.record_kind`);
+  }
+  if (source.schema_version !== "1.0") {
+    failLearning("learning_schema_version_invalid", `${path} must use schema_version 1.0`, `${path}.schema_version`);
+  }
+  const stable_ref = stableLearningRef(own(source, "stable_ref", "stableRef"), `${path}.stable_ref`);
+  const version_id = own(source, "version_id", "versionId");
+  const payload = copyLearning(source);
+  delete payload.version_id;
+  delete payload.versionId;
+  try {
+    parseVersionId({ payload, stable_ref, version_id });
+  } catch (error) {
+    failLearning(
+      "learning_record_version_invalid",
+      `${path} VersionID does not bind its canonical bytes: ${error instanceof Error ? error.message : String(error)}`,
+      `${path}.version_id`,
+    );
+  }
+  return deepFreeze(copyLearning(source));
+}
+
+function canonicalAliases(source) {
+  const fields = canonicalFields(source);
+  const aliases = [
+    ["independence_group", "independentGroup"],
+    ["proposal_ref", "proposalRef"],
+    ["proposal_version_id", "proposalVersionId"],
+    ["receipt_id", "receiptId"],
+    ["source_ref", "sourceRef"],
+    ["source_version_id", "sourceVersionId"],
+  ];
+  for (const [canonical, alias] of aliases) {
+    if (fields[canonical] === undefined && fields[alias] !== undefined) fields[canonical] = fields[alias];
+    delete fields[alias];
+  }
+  return fields;
+}
+
+function applyBindings(fields, bindings, path) {
+  for (const [key, expected] of Object.entries(bindings)) {
+    if (fields[key] !== undefined && fields[key] !== expected) {
+      failLearning("learning_link_mismatch", `${path}.${key} does not match its governed parent`, `${path}.${key}`);
+    }
+    fields[key] = expected;
+  }
+  return fields;
+}
+
+export function makeEvidenceRecords(values, options) {
+  if (!Array.isArray(values) || values.length === 0) {
+    failLearning("learning_evidence_required", "at least one evidence record is required", options.path);
+  }
+  return values.map((item, index) => {
+    const path = `${options.path}/${index}`;
+    const source = learningObject(item, path);
+    const stableRef = stableLearningRef(
+      own(source, "stable_ref", "stableRef"),
+      `${path}.stable_ref`,
+      `sg:evidence/${options.slug}-${index + 1}`,
+    );
+    if (parseStableRef(stableRef).kind !== "evidence") {
+      failLearning("learning_record_kind_invalid", `${path}.stable_ref must use sg:evidence/...`, `${path}.stable_ref`);
+    }
+    const fields = applyBindings(canonicalAliases(source), options.bindings ?? {}, path);
+    return makeLearningRecord(source, stableRef, "evidence_link", fields);
+  });
+}
+
+export function makeValidationRecord(value, options) {
+  const source = learningObject(value, options.path);
+  const fields = canonicalAliases(source);
+  if (fields.validator === undefined && fields.validator_actor !== undefined) fields.validator = fields.validator_actor;
+  if (fields.validator_version === undefined && fields.version !== undefined) fields.validator_version = fields.version;
+  delete fields.validator_actor;
+  delete fields.version;
+  fields.validator = textLearning(fields.validator, `${options.path}.validator`).trim();
+  const status = textLearning(fields.status, `${options.path}.status`).toUpperCase();
+  if (!PASSING.has(status)) {
+    failLearning("learning_validation_not_passed", `${options.path} must have a passing status`, `${options.path}.status`);
+  }
+  fields.status = status;
+  applyBindings(fields, options.bindings ?? {}, options.path);
+  if (parseStableRef(options.stableRef).kind !== "validation") {
+    failLearning("learning_record_kind_invalid", `${options.path}.stable_ref must use sg:validation/...`, `${options.path}.stable_ref`);
+  }
+  return makeLearningRecord(source, options.stableRef, "validation_report", fields);
+}
+
+export function assertLink(record, key, expected, path) {
+  if (record[key] !== expected) {
+    failLearning("learning_link_mismatch", `${path}.${key} must bind ${expected}`, `${path}.${key}`);
+  }
+}
+
+export function assertEvidenceRecords(values, bindings, path = "evidence") {
+  if (!Array.isArray(values) || values.length === 0) {
+    failLearning("learning_evidence_required", `${path} requires at least one evidence record`, path);
+  }
+  return values.map((value, index) => {
+    const record = assertLearningRecord(value, "evidence_link", `${path}/${index}`);
+    if (parseStableRef(record.stable_ref).kind !== "evidence") {
+      failLearning("learning_record_kind_invalid", `${path}/${index} must use sg:evidence/...`, `${path}/${index}/stable_ref`);
+    }
+    for (const [key, expected] of Object.entries(bindings ?? {})) assertLink(record, key, expected, `${path}/${index}`);
+    return record;
+  });
+}
+
+export function assertValidationRecord(value, bindings, path = "validation") {
+  const record = assertLearningRecord(value, "validation_report", path);
+  if (parseStableRef(record.stable_ref).kind !== "validation") {
+    failLearning("learning_record_kind_invalid", `${path} must use sg:validation/...`, `${path}.stable_ref`);
+  }
+  if (!PASSING.has(String(record.status).toUpperCase())) {
+    failLearning("learning_validation_not_passed", `${path} must have a passing status`, `${path}.status`);
+  }
+  const validator = textLearning(record.validator, `${path}.validator`);
+  if (validator !== validator.trim()) {
+    failLearning("learning_actor_invalid", `${path}.validator must be canonical`, `${path}.validator`);
+  }
+  for (const [key, expected] of Object.entries(bindings ?? {})) assertLink(record, key, expected, path);
+  return record;
+}
+
+export function nextLearningRegistry(registry, targetRef, versionId) {
+  if (registry === undefined) return undefined;
+  const source = learningObject(registry, "registry");
+  const entries = own(source, "entries");
+  if (!Array.isArray(entries)) {
+    failLearning("learning_registry_invalid", "registry.entries must be an array", "registry.entries");
+  }
+  const nextEntries = entries.map(copyLearning);
+  const index = nextEntries.findIndex((entry) => own(entry, "stable_ref", "stableRef") === targetRef);
+  const replacement = { stable_ref: targetRef, version_id: versionId };
+  if (index === -1) nextEntries.push(replacement);
+  else nextEntries[index] = { ...nextEntries[index], ...replacement };
+  nextEntries.sort((a, b) => {
+    const left = String(own(a, "stable_ref", "stableRef"));
+    const right = String(own(b, "stable_ref", "stableRef"));
+    return left < right ? -1 : left > right ? 1 : 0;
+  });
+  return deepFreeze({ ...copyLearning(source), entries: nextEntries });
+}

package/scripts/agent-native/learning.mjs

@@ -0,0 +1,247 @@
+import { deepFreeze } from "./canonical-json.mjs";
+import { parseStableRef } from "./identity.mjs";
+import {
+  LearningError, assertEvidenceRecords, assertLearningRecord, assertLink, assertValidationRecord,
+  compactLearning, copyLearning, failLearning, learningObject, makeEvidenceRecords,
+  makeLearningRecord, makeValidationRecord, nextLearningRegistry, own, stableLearningRef,
+  textLearning,
+} from "./learning-records.mjs";
+
+const ACCEPTED = new Set(["ACCEPT", "ACCEPTED", "APPROVE", "APPROVED"]);
+const DECISIONS = new Set([...ACCEPTED, "REJECT", "REJECTED", "DENY", "DENIED", "DEFER", "DEFERRED"]);
+
+export { LearningError };
+
+function slug(ref) {
+  return ref.slice(ref.indexOf("/") + 1);
+}
+
+function requireRefKind(ref, kind, path) {
+  if (parseStableRef(ref).kind !== kind) {
+    failLearning("learning_record_kind_invalid", `${path} must use sg:${kind}/...`, path);
+  }
+  return ref;
+}
+
+function actorOf(value, path) {
+  return textLearning(
+    own(value, "verifier", "verifier_actor", "verifierActor", "verified_by", "verifiedBy", "actor", "subject"),
+    path,
+  ).trim();
+}
+
+function blocked(code, message, fields = {}) {
+  return deepFreeze({ ...fields, code, message, ok: false, status: "BLOCKED" });
+}
+
+function decisionOf(value) {
+  const decision = typeof value === "string" ? value : own(value, "decision", "status", "disposition");
+  return typeof decision === "string" ? decision.toUpperCase() : undefined;
+}
+
+function assertProposal(value) {
+  const proposal = assertLearningRecord(value, "learning_proposal", "proposal");
+  requireRefKind(proposal.stable_ref, "proposal", "proposal.stable_ref");
+  const proposer = textLearning(proposal.proposer, "proposal.proposer");
+  if (proposer !== proposer.trim()) {
+    failLearning("learning_actor_invalid", "proposal.proposer must be canonical", "proposal.proposer");
+  }
+  learningObject(proposal.claim, "proposal.claim");
+  if (!Array.isArray(proposal.changes) || proposal.changes.length === 0) {
+    failLearning("learning_changes_required", "proposal requires at least one proposed change", "proposal.changes");
+  }
+  assertEvidenceRecords(proposal.evidence, undefined, "proposal.evidence");
+  assertValidationRecord(proposal.validation, undefined, "proposal.validation");
+  return proposal;
+}
+
+function proposalOf(input) {
+  const proposal = assertProposal(own(input, "proposal"));
+  return { proposal, proposalRef: proposal.stable_ref };
+}
+
+function assertVerification(value, proposal) {
+  const verification = assertLearningRecord(value, "learning_verification", "verification");
+  requireRefKind(verification.stable_ref, "validation", "verification.stable_ref");
+  assertLink(verification, "proposal_ref", proposal.stable_ref, "verification");
+  assertLink(verification, "proposal_version_id", proposal.version_id, "verification");
+  const verifier = actorOf(verification, "verification.verifier");
+  if (verifier === proposal.proposer || verification.independent !== true || verification.verified !== true) {
+    failLearning("learning_verification_requires_independence", "verification must be independent from the proposer", "verification.verifier");
+  }
+  assertLink(verification, "independent_of", proposal.proposer, "verification");
+  const bindings = { proposal_ref: proposal.stable_ref, proposal_version_id: proposal.version_id };
+  assertEvidenceRecords(verification.evidence, bindings, "verification.evidence");
+  const validation = assertValidationRecord(verification.validation, bindings, "verification.validation");
+  if (validation.validator === proposal.proposer) {
+    failLearning("learning_verification_requires_independence", "proposal author cannot validate its verification", "verification.validation.validator");
+  }
+  return verification;
+}
+
+function assertDecision(value, proposal, verification) {
+  const governance = assertLearningRecord(value, "governance_decision", "governance_decision");
+  requireRefKind(governance.stable_ref, "governance", "governance_decision.stable_ref");
+  assertLink(governance, "proposal_ref", proposal.stable_ref, "governance_decision");
+  assertLink(governance, "proposal_version_id", proposal.version_id, "governance_decision");
+  assertLink(governance, "verification_ref", verification.stable_ref, "governance_decision");
+  assertLink(governance, "verification_version_id", verification.version_id, "governance_decision");
+  const actor = actorOf(governance, "governance_decision.actor");
+  if (actor === proposal.proposer || actor === verification.verifier) {
+    failLearning("learning_governance_requires_independence", "proposal author or verifier cannot govern the same proposal", "governance_decision.actor");
+  }
+  if (!DECISIONS.has(decisionOf(governance))) {
+    failLearning("learning_decision_invalid", "governance decision has an unsupported disposition", "governance_decision.decision");
+  }
+  return governance;
+}
+
+export function createProposal(input) {
+  const source = learningObject(input, "createProposal");
+  const ref = requireRefKind(stableLearningRef(
+    own(source, "stable_ref", "stableRef", "proposal_id", "proposalId"),
+    "createProposal.stable_ref",
+  ), "proposal", "createProposal.stable_ref");
+  const claim = learningObject(own(source, "claim"), "createProposal.claim");
+  const changes = own(source, "changes", "patch", "delta");
+  if (!Array.isArray(changes) || changes.length === 0) {
+    failLearning("learning_changes_required", "proposal requires at least one proposed change", "changes");
+  }
+  const proposer = textLearning(own(source, "proposer", "proposed_by", "proposedBy"), "proposer").trim();
+  const evidence = makeEvidenceRecords(own(source, "evidence", "evidence_links", "evidenceLinks"), {
+    path: "evidence",
+    slug: `${slug(ref)}-proposal-evidence`,
+  });
+  const validation = makeValidationRecord(own(source, "validation"), {
+    path: "validation",
+    stableRef: `sg:validation/${slug(ref)}-proposal`,
+  });
+  return makeLearningRecord(source, ref, "learning_proposal", {
+    changes: copyLearning(changes),
+    claim: copyLearning(claim),
+    evidence,
+    proposal_id: ref,
+    proposer,
+    source_task: copyLearning(own(source, "source_task", "sourceTask", "task_id", "taskId")),
+    status: "PROPOSED",
+    validation,
+  });
+}
+
+export function verifyProposal(input) {
+  const source = learningObject(input, "verifyProposal");
+  const { proposal, proposalRef } = proposalOf(source);
+  const verifier = actorOf(source, "verifier");
+  const independentOf = own(source, "independent_of", "independentOf");
+  if (verifier === proposal.proposer || (independentOf !== undefined && independentOf !== proposal.proposer)) {
+    return blocked("learning_verification_requires_independence", "verifier must be independent from proposer", {
+      independent: false, verified: false, verifier,
+    });
+  }
+  const bindings = { proposal_ref: proposalRef, proposal_version_id: proposal.version_id };
+  const evidence = makeEvidenceRecords(own(source, "evidence", "evidence_links", "evidenceLinks"), {
+    bindings,
+    path: "evidence",
+    slug: `${slug(proposalRef)}-verification-evidence`,
+  });
+  const validation = makeValidationRecord(own(source, "validation"), {
+    bindings,
+    path: "validation",
+    stableRef: `sg:validation/${slug(proposalRef)}-verification-report`,
+  });
+  if (validation.validator === proposal.proposer) {
+    return blocked("learning_verification_requires_independence", "proposal author cannot validate its verification", {
+      independent: false, verified: false, verifier,
+    });
+  }
+  const ref = `sg:validation/${slug(proposalRef)}-verification`;
+  return makeLearningRecord(source, ref, "learning_verification", {
+    evidence,
+    independent: true,
+    independent_of: proposal.proposer,
+    proposal_ref: proposalRef,
+    proposal_version_id: proposal.version_id,
+    status: "VERIFIED",
+    validation,
+    verified: true,
+    verifier,
+    verifier_actor: verifier,
+  });
+}
+
+export function decideProposal(input) {
+  const source = learningObject(input, "decideProposal");
+  const { proposal, proposalRef } = proposalOf(source);
+  const verification = assertVerification(own(source, "verification"), proposal);
+  const provided = learningObject(
+    own(source, "governance_decision", "governanceDecision") ?? source,
+    "governanceDecision",
+  );
+  const decision = textLearning(own(source, "decision") ?? decisionOf(provided), "decision").toUpperCase();
+  if (!DECISIONS.has(decision)) failLearning("learning_decision_invalid", "decision is unsupported", "decision");
+  const actor = actorOf(provided, "governanceDecision.actor");
+  if (actor === proposal.proposer || actor === verification.verifier) {
+    return blocked("learning_governance_requires_independence", "proposal author or verifier cannot govern the same proposal", { actor });
+  }
+  const ref = `sg:governance/${slug(proposalRef)}-decision`;
+  return makeLearningRecord(source, ref, "governance_decision", {
+    actor,
+    decided_at: copyLearning(own(provided, "decided_at", "decidedAt")),
+    decision,
+    proposal_ref: proposalRef,
+    proposal_version_id: proposal.version_id,
+    status: decision,
+    verification_ref: verification.stable_ref,
+    verification_version_id: verification.version_id,
+  });
+}
+
+export function promoteProposal(input) {
+  const source = learningObject(input, "promoteProposal");
+  const { proposal, proposalRef } = proposalOf(source);
+  const rawVerification = own(source, "verification") ?? own(proposal, "verification");
+  if (!rawVerification) return blocked("learning_promotion_requires_verification", "promotion requires verification", { promoted: false, proposal_ref: proposalRef });
+  const verification = assertVerification(rawVerification, proposal);
+  const rawGovernance = own(source, "governance_decision", "governanceDecision")
+    ?? (typeof own(source, "decision") === "object" ? own(source, "decision") : undefined);
+  if (!rawGovernance) return blocked("learning_promotion_requires_governance", "promotion requires governance", { promoted: false, proposal_ref: proposalRef });
+  const governance = assertDecision(rawGovernance, proposal, verification);
+  if (!ACCEPTED.has(decisionOf(governance))) {
+    return blocked("learning_promotion_requires_governance", "promotion requires an accepted decision", { promoted: false, proposal_ref: proposalRef });
+  }
+  const targetRef = stableLearningRef(
+    own(source, "target_stable_ref", "targetStableRef", "target_ref", "targetRef")
+      ?? own(proposal, "target_stable_ref", "targetStableRef")
+      ?? own(proposal.claim, "stable_ref", "stableRef"),
+    "target_stable_ref",
+  );
+  const version = makeLearningRecord({}, targetRef, "governed_version", {
+    changes: copyLearning(proposal.changes),
+    claim: copyLearning(proposal.claim),
+    evidence: copyLearning(verification.evidence),
+    governance_decision_version_id: governance.version_id,
+    proposal_ref: proposalRef,
+    proposal_version_id: proposal.version_id,
+    verification_version_id: verification.version_id,
+  });
+  const receipt = makeLearningRecord({}, `sg:governance/${slug(proposalRef)}-promotion`, "promotion_receipt", {
+    governed_version_id: version.version_id,
+    governance_decision_version_id: governance.version_id,
+    outcome: "PROMOTED",
+    proposal_ref: proposalRef,
+    proposal_version_id: proposal.version_id,
+    verification_version_id: verification.version_id,
+  });
+  return deepFreeze(compactLearning({
+    promoted: true,
+    proposal_ref: proposalRef,
+    receipt,
+    registry: nextLearningRegistry(own(source, "registry"), targetRef, version.version_id),
+    status: "PROMOTED",
+    version,
+    version_id: version.version_id,
+  }));
+}
+
+export const createLearningProposal = createProposal, verifyLearningProposal = verifyProposal;
+export const decideLearningProposal = decideProposal, promoteLearningProposal = promoteProposal;

package/scripts/agent-native/mcp-adapter.mjs

@@ -0,0 +1,173 @@
+import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import {
+  CallToolRequestSchema,
+  ErrorCode,
+  ListToolsRequestSchema,
+  McpError,
+} from "@modelcontextprotocol/sdk/types.js";
+
+import { canonicalize } from "./canonical-json.mjs";
+import { parseStableRef } from "./identity.mjs";
+import { agentNativeRegistry } from "./registry.mjs";
+
+function operationInputSchema(operation) {
+  const schema = structuredClone(operation.input_schema ?? { type: "object" });
+  if (Object.hasOwn(schema.properties ?? {}, "reference")) {
+    schema.properties.stable_ref = structuredClone(schema.properties.reference);
+    schema.required = (schema.required ?? []).filter((name) => name !== "reference");
+    schema.anyOf = [{ required: ["reference"] }, { required: ["stable_ref"] }];
+  }
+  return schema;
+}
+
+function normalizeInput(input) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) return {};
+  if (!Object.hasOwn(input, "stable_ref")) return input;
+  const normalized = { ...input };
+  if (!Object.hasOwn(normalized, "reference")) normalized.reference = normalized.stable_ref;
+  delete normalized.stable_ref;
+  return normalized;
+}
+
+function toolResponse(envelope) {
+  return {
+    content: [{ type: "text", text: canonicalize(envelope) }],
+    isError: envelope.ok !== true,
+    structuredContent: envelope,
+  };
+}
+
+function deniedTool(operation) {
+  return toolResponse({
+    failures: [{
+      code: "operation_not_exposed",
+      message: `operation ${operation} is not exposed by the read-only MCP surface`,
+      path: "operation",
+    }],
+    ok: false,
+    operation,
+  });
+}
+
+function toolDefinition(operation) {
+  return {
+    annotations: {
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+      readOnlyHint: true,
+    },
+    description: operation.description,
+    inputSchema: operationInputSchema(operation),
+    name: operation.name,
+  };
+}
+
+function resourceContents(uri, value) {
+  return {
+    contents: [{
+      mimeType: "application/json",
+      text: canonicalize(value),
+      uri,
+    }],
+  };
+}
+
+function assertRegistry(registry) {
+  if (!registry || typeof registry.invoke !== "function" || !Array.isArray(registry.operations)) {
+    throw new TypeError("MCP registry must expose invoke and operations");
+  }
+  if (!registry.fixture?.manifest || !registry.selfDescription) {
+    throw new TypeError("MCP registry must expose an immutable manifest and self-description");
+  }
+  for (const operation of registry.operations) {
+    if (typeof operation.read_only !== "boolean") throw new TypeError(`${operation.name} must declare read_only`);
+    if (operation.read_only && operation.effect_class !== "NONE") {
+      throw new TypeError(`${operation.name} cannot expose ${operation.effect_class} effects as read-only`);
+    }
+  }
+}
+
+function objectUri(stableRef) {
+  return `sg://object/${encodeURIComponent(stableRef)}`;
+}
+
+function objectReference(encoded) {
+  if (typeof encoded !== "string" || encoded.length === 0) {
+    throw new McpError(ErrorCode.InvalidParams, "object reference must be an encoded StableRef");
+  }
+  let decoded;
+  try { decoded = decodeURIComponent(encoded); } catch {
+    throw new McpError(ErrorCode.InvalidParams, "object reference contains invalid percent encoding");
+  }
+  try { return parseStableRef(decoded).stable_ref; } catch {
+    throw new McpError(ErrorCode.InvalidParams, "object reference must decode to one governed StableRef");
+  }
+}
+
+function resolveObject(registry, encoded) {
+  const resolved = registry.invoke("resolve", { reference: objectReference(encoded) });
+  if (resolved.ok) return resolved.result;
+  const failure = resolved.failures?.[0] ?? { code: "object_not_found", message: "object could not be resolved" };
+  throw new McpError(ErrorCode.InvalidParams, `${failure.code}: ${failure.message}`);
+}
+
+export function createStyleGalleryMcpServer({ registry = agentNativeRegistry } = {}) {
+  assertRegistry(registry);
+  const server = new McpServer({ name: "StyleGallery", version: "1.0.0" });
+  const operations = registry.operations
+    .filter((operation) => operation.read_only)
+    .sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
+  const operationByName = new Map(operations.map((operation) => [operation.name, operation]));
+
+  server.registerResource(
+    "stylegallery-self-description",
+    "sg://self",
+    {
+      description: "Immutable StyleGallery self-description and conformance profile.",
+      mimeType: "application/json",
+    },
+    async () => resourceContents("sg://self", registry.selfDescription),
+  );
+  server.registerResource(
+    "stylegallery-manifest",
+    "sg://manifest",
+    {
+      description: "Immutable manifest for the agent-native StyleGallery fixture.",
+      mimeType: "application/json",
+    },
+    async () => resourceContents("sg://manifest", registry.fixture.manifest),
+  );
+  server.registerResource(
+    "stylegallery-object",
+    new ResourceTemplate("sg://object/{reference}", {
+      list: async () => ({
+        resources: registry.fixture.records.map((record) => ({
+          description: `Immutable ${record.record_kind} record resolved from the common registry.`,
+          mimeType: "application/json",
+          name: record.stable_ref,
+          uri: objectUri(record.stable_ref),
+        })),
+      }),
+    }),
+    {
+      description: "Resolve one encoded StableRef through the immutable common registry.",
+      mimeType: "application/json",
+    },
+    async (uri, variables) => resourceContents(uri.toString(), resolveObject(registry, variables.reference)),
+  );
+
+  server.server.registerCapabilities({ tools: { listChanged: false } });
+  server.server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: operations.map(toolDefinition),
+  }));
+  server.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const operation = operationByName.get(request.params.name);
+    if (!operation) return deniedTool(request.params.name);
+    const input = normalizeInput(request.params.arguments ?? {});
+    return toolResponse(registry.invoke(operation.name, input));
+  });
+  return server;
+}
+
+export const createMcpServer = createStyleGalleryMcpServer;