stylegallery 0.1.0

package/scripts/agent-native/queries.mjs

@@ -0,0 +1,173 @@
+import { canonicalize, deepFreeze } from "./canonical-json.mjs";
+import { parseStableRef, parseVersionId } from "./identity.mjs";
+import { aggregateEvidence } from "./knowledge.mjs";
+import { buildContextPackage, buildViewSnapshot } from "./retrieval.mjs";
+
+export class QueryError extends TypeError {
+  constructor(code, message, recordPath = "") {
+    super(message);
+    this.name = "QueryError";
+    this.code = code;
+    if (recordPath) this.path = recordPath;
+  }
+}
+
+function fail(code, message, recordPath = "") {
+  throw new QueryError(code, message, recordPath);
+}
+
+function compare(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+function inputReference(input) {
+  if (typeof input === "string") return input;
+  if (!input || typeof input !== "object" || Array.isArray(input)) return undefined;
+  return input.reference ?? input.ref ?? input.stable_ref ?? input.stableRef ?? input.version_id ?? input.versionId;
+}
+
+function indexFixture(fixture) {
+  if (!fixture || !Array.isArray(fixture.records)) fail("registry_fixture_invalid", "fixture.records must be an array");
+  const records = [...fixture.records].sort((left, right) => compare(left.stable_ref, right.stable_ref) || compare(left.version_id, right.version_id));
+  const byVersion = new Map(records.map((record) => [record.version_id, record]));
+  const byStableRef = new Map();
+  for (const record of records) byStableRef.set(record.stable_ref, record);
+  return { byStableRef, byVersion, records };
+}
+
+function normalizeReference(input) {
+  const reference = inputReference(input);
+  if (typeof reference !== "string" || reference.length === 0) {
+    fail("argument_value_required", "a StableRef or VersionID is required", "reference");
+  }
+  if (reference.includes("@")) {
+    try { return { reference, version: true, stableRef: parseVersionId(reference).stable_ref }; } catch {
+      fail("version_id_malformed", "reference must be StableRef@sha256:<64 lowercase hex>", "reference");
+    }
+  }
+  try { return { reference, version: false, stableRef: parseStableRef(reference).stable_ref }; } catch {
+    fail("stable_ref_malformed", "reference must match sg:<kind>/<kebab-id>", "reference");
+  }
+}
+
+export function resolveRecord(fixture, input) {
+  const normalized = normalizeReference(input);
+  const index = indexFixture(fixture);
+  const record = normalized.version ? index.byVersion.get(normalized.reference) : index.byStableRef.get(normalized.stableRef);
+  if (!record) {
+    const code = normalized.version ? "version_id_unknown" : "stable_ref_unknown";
+    fail(code, `no immutable fixture record exists for ${normalized.reference}`, "reference");
+  }
+  return record;
+}
+
+function linked(records, kind, claimRef) {
+  return records.filter((record) => record.record_kind === kind && record.claim_ref === claimRef);
+}
+
+function claimsFor(index, subject) {
+  if (subject.record_kind === "claim") return [subject];
+  const declared = new Set(Array.isArray(subject.claim_refs) ? subject.claim_refs : []);
+  return index.records.filter((record) => record.record_kind === "claim"
+    && (record.subject_ref === subject.stable_ref || declared.has(record.stable_ref)));
+}
+
+export function queryClaims(fixture, input) {
+  const subject = resolveRecord(fixture, input);
+  const index = indexFixture(fixture);
+  const claims = claimsFor(index, subject).map((claim) => {
+    const evidence = linked(index.records, "evidence_link", claim.stable_ref);
+    const validations = linked(index.records, "validation_report", claim.stable_ref);
+    const governance = linked(index.records, "governance_decision", claim.stable_ref);
+    const policy = linked(index.records, "policy_disposition", claim.stable_ref);
+    return {
+      aggregate: aggregateEvidence({ claim, evidence_links: evidence }),
+      claim,
+      evidence,
+      governance,
+      policy_dispositions: policy,
+      validations,
+    };
+  });
+  return deepFreeze({ claims, subject_ref: subject.stable_ref, subject_version_id: subject.version_id });
+}
+
+function contextMembers(fixture, subject) {
+  const graph = queryClaims(fixture, subject.stable_ref);
+  const related = graph.claims.flatMap((entry) => [
+    entry.claim,
+    ...entry.evidence,
+    ...entry.validations,
+    ...entry.governance,
+    ...entry.policy_dispositions,
+  ]);
+  const unique = new Map([subject, ...related].map((record) => [record.version_id, record]));
+  return [...unique.values()];
+}
+
+function refSlug(stableRef) {
+  return stableRef.replace(/^sg:/, "").replace("/", "-");
+}
+
+export function queryContext(fixture, input) {
+  const subject = resolveRecord(fixture, input);
+  const members = contextMembers(fixture, subject);
+  const slug = refSlug(subject.stable_ref);
+  const snapshot = buildViewSnapshot({
+    heads: [fixture.manifest.version_id],
+    max_members: 64,
+    members,
+    policy: "sg:policy/editorial-profile-read",
+    snapshot_ref: `sg:view/${slug}-snapshot`,
+    view_spec: { stable_ref: `sg:view/${slug}-snapshot`, subject_ref: subject.stable_ref },
+  });
+  return buildContextPackage({
+    budget: { tokens: 32768 },
+    context_ref: `sg:view/${slug}-context`,
+    members,
+    policy: "sg:policy/editorial-profile-read",
+    query: subject.stable_ref,
+    query_class: "stable_ref",
+    retriever: "fixture-registry@1",
+    snapshot,
+  });
+}
+
+export function queryOperations(operationSpecs) {
+  if (!Array.isArray(operationSpecs)) fail("registry_operations_invalid", "operation specs must be an array");
+  const operations = [...operationSpecs].sort((left, right) => compare(left.name, right.name));
+  return deepFreeze({ operations });
+}
+
+export function queryDiscover(description) {
+  if (!description || typeof description !== "object" || Array.isArray(description)) {
+    fail("self_description_invalid", "discover requires a self-description object");
+  }
+  return description;
+}
+
+export function queryRetrieve(fixture, input = {}) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) fail("retrieve_input_invalid", "retrieve input must be an object");
+  const query = input.query ?? "";
+  if (typeof query !== "string") fail("retrieve_query_invalid", "retrieve query must be a string", "query");
+  const limit = input.limit ?? 32;
+  if (!Number.isInteger(limit) || limit < 0 || limit > 256) fail("retrieve_limit_invalid", "retrieve limit must be an integer from 0 to 256", "limit");
+  const needle = query.toLowerCase();
+  const members = indexFixture(fixture).records
+    .filter((record) => needle.length === 0 || canonicalize(record).toLowerCase().includes(needle))
+    .slice(0, limit);
+  return buildViewSnapshot({
+    heads: [fixture.manifest.version_id],
+    max_members: limit,
+    members,
+    snapshot_ref: "sg:view/registry-retrieval",
+    view_spec: { query, stable_ref: "sg:view/registry-retrieval" },
+  });
+}
+
+export const resolve = resolveRecord;
+export const claims = queryClaims;
+export const context = queryContext;
+export const ops = queryOperations;
+export const discover = queryDiscover;
+export const retrieve = queryRetrieve;

package/scripts/agent-native/registry.mjs

@@ -0,0 +1,154 @@
+import { deepFreeze } from "./canonical-json.mjs";
+import {
+  createTask,
+  reconcileEffect,
+  recordEffectAttempt,
+  startRun,
+} from "./execution.mjs";
+import { agentNativeFixture } from "./fixture.mjs";
+import {
+  createProposal,
+  decideProposal,
+  promoteProposal,
+  verifyProposal,
+} from "./learning.mjs";
+import {
+  queryClaims,
+  queryContext,
+  queryDiscover,
+  queryOperations,
+  queryRetrieve,
+  resolveRecord,
+} from "./queries.mjs";
+import { createSelfDescription } from "./self-description.mjs";
+
+export class RegistryError extends TypeError {
+  constructor(code, message, recordPath = "") {
+    super(message);
+    this.name = "RegistryError";
+    this.code = code;
+    if (recordPath) this.path = recordPath;
+  }
+}
+
+function failure(code, message, recordPath = "") {
+  return recordPath ? { code, message, path: recordPath } : { code, message };
+}
+
+function compareFailures(left, right) {
+  const leftKey = `${left.code}\u0000${left.path ?? ""}\u0000${left.message}`;
+  const rightKey = `${right.code}\u0000${right.path ?? ""}\u0000${right.message}`;
+  return leftKey < rightKey ? -1 : leftKey > rightKey ? 1 : 0;
+}
+
+function failed(operation, failures) {
+  return deepFreeze({ failures: [...failures].sort(compareFailures), ok: false, operation });
+}
+
+function succeeded(operation, result) {
+  return deepFreeze({ ok: true, operation, result });
+}
+
+function validateValue(schema, value, recordPath) {
+  if (schema.type === "string" && typeof value !== "string") return failure("operation_input_invalid", `${recordPath} must be a string`, recordPath);
+  if (schema.type === "integer" && !Number.isInteger(value)) return failure("operation_input_invalid", `${recordPath} must be an integer`, recordPath);
+  if (typeof schema.minimum === "number" && value < schema.minimum) return failure("operation_input_invalid", `${recordPath} must be at least ${schema.minimum}`, recordPath);
+  return undefined;
+}
+
+function validateInput(spec, input) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    return [failure("operation_input_invalid", "operation input must be an object")];
+  }
+  const schema = spec.input_schema ?? { type: "object" };
+  const properties = schema.properties ?? {};
+  const failures = [];
+  for (const key of schema.required ?? []) {
+    if (!Object.hasOwn(input, key)) failures.push(failure("operation_input_required", `${key} is required`, key));
+  }
+  if (schema.additionalProperties === false) {
+    for (const key of Object.keys(input)) if (!Object.hasOwn(properties, key)) {
+      failures.push(failure("operation_input_unknown", `${key} is not accepted by ${spec.name}`, key));
+    }
+  }
+  for (const [key, value] of Object.entries(input)) {
+    if (!Object.hasOwn(properties, key)) continue;
+    const issue = validateValue(properties[key], value, key);
+    if (issue) failures.push(issue);
+  }
+  return failures;
+}
+
+function handlers(fixture, operations, selfDescription) {
+  return new Map([
+    ["claims", (input) => queryClaims(fixture, input)],
+    ["context", (input) => queryContext(fixture, input)],
+    ["discover", () => queryDiscover(selfDescription)],
+    ["effect.record", (input) => recordEffectAttempt(input)],
+    ["effect.reconcile", (input) => reconcileEffect(input)],
+    ["ops", () => queryOperations(operations)],
+    ["proposal.create", (input) => createProposal(input)],
+    ["proposal.decide", (input) => decideProposal(input)],
+    ["proposal.promote", (input) => promoteProposal(input)],
+    ["proposal.verify", (input) => verifyProposal(input)],
+    ["resolve", (input) => resolveRecord(fixture, input)],
+    ["retrieve", (input) => queryRetrieve(fixture, input)],
+    ["run.start", (input) => startRun(input)],
+    ["task.create", (input) => createTask(input)],
+  ]);
+}
+
+function assertOperationMetadata(operations, operationHandlers) {
+  for (const operation of operations) {
+    if (typeof operation.read_only !== "boolean") {
+      throw new RegistryError("operation_read_only_required", `${operation.name} must declare read_only`);
+    }
+    if (operation.read_only && operation.effect_class !== "NONE") {
+      throw new RegistryError("operation_read_only_effect_invalid", `${operation.name} cannot be read-only with ${operation.effect_class} effects`);
+    }
+    if (!operationHandlers.has(operation.name)) {
+      throw new RegistryError("operation_handler_missing", `${operation.name} has no common-registry handler`);
+    }
+  }
+}
+
+export function createOperationRegistry({ fixture = agentNativeFixture } = {}) {
+  const operations = fixture.records
+    .filter((record) => record.record_kind === "operation")
+    .sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
+  if (new Set(operations.map((operation) => operation.name)).size !== operations.length) {
+    throw new RegistryError("operation_name_duplicate", "operation names must be unique");
+  }
+  const selfDescription = createSelfDescription({ fixture, operations });
+  const operationByName = new Map(operations.map((operation) => [operation.name, operation]));
+  const operationHandlers = handlers(fixture, operations, selfDescription);
+  assertOperationMetadata(operations, operationHandlers);
+  const invoke = (operation, input = {}) => {
+    if (typeof operation !== "string" || operation.length === 0) {
+      return failed(null, [failure("operation_required", "operation name is required")]);
+    }
+    const spec = operationByName.get(operation);
+    if (!spec || !operationHandlers.has(operation)) {
+      return failed(operation, [failure("operation_unknown", `unknown operation ${operation}`, "operation")]);
+    }
+    const inputFailures = validateInput(spec, input);
+    if (inputFailures.length > 0) return failed(operation, inputFailures);
+    try { return succeeded(operation, operationHandlers.get(operation)(input)); } catch (error) {
+      return failed(operation, [failure(error?.code ?? "operation_failed", error instanceof Error ? error.message : String(error), error?.path)]);
+    }
+  };
+  return Object.freeze({ fixture, invoke, operations: deepFreeze([...operations]), selfDescription });
+}
+
+export const agentNativeRegistry = createOperationRegistry();
+export const readOnlyOperationNames = deepFreeze(agentNativeRegistry.operations
+  .filter((operation) => operation.read_only)
+  .map((operation) => operation.name));
+
+export function invokeOperation(operation, input = {}, registry = agentNativeRegistry) {
+  if (!registry || typeof registry.invoke !== "function") throw new RegistryError("registry_invalid", "registry must expose invoke");
+  return registry.invoke(operation, input);
+}
+
+export const invokeRegistryOperation = invokeOperation;
+export const operationRegistry = agentNativeRegistry;

package/scripts/agent-native/retrieval.mjs

@@ -0,0 +1,171 @@
+import { cloneAndFreeze, canonicalize, hashCanonical } from "./canonical-json.mjs";
+import { createStableRef } from "./identity.mjs";
+
+function pick(value, ...keys) {
+  if (!value || typeof value !== "object") return undefined;
+  for (const key of keys) if (Object.hasOwn(value, key)) return value[key];
+  return undefined;
+}
+
+function objectInput(value, name) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new TypeError(`${name} expects an object`);
+  return value;
+}
+
+function copy(value) {
+  return value === undefined ? undefined : structuredClone(value);
+}
+
+function canonicalFreeze(value) {
+  return cloneAndFreeze(JSON.parse(canonicalize(value)));
+}
+
+function refOf(value) {
+  return pick(value, "stable_ref", "stableRef", "ref", "id") ?? "";
+}
+
+function versionOf(value) {
+  return pick(value, "version_id", "versionId", "version") ?? "";
+}
+
+function memberReference(member) {
+  const reference = {};
+  const stableRef = refOf(member);
+  const versionId = versionOf(member);
+  const contentHash = pick(member, "content_sha256", "contentHash", "sha256");
+  if (stableRef) reference.stable_ref = stableRef;
+  if (versionId) reference.version_id = versionId;
+  if (contentHash) reference.content_sha256 = contentHash;
+  return reference;
+}
+
+function sortedUniqueStrings(value) {
+  if (value === undefined || value === null) return [];
+  if (!Array.isArray(value)) throw new TypeError("heads must be an array");
+  return [...new Set(value.map((item) => {
+    if (typeof item !== "string" || item.length === 0) throw new TypeError("head IDs must be non-empty strings");
+    return item;
+  }))].sort();
+}
+
+function normalizeMembers(value, maxMembers = 256) {
+  const source = value ?? [];
+  if (!Array.isArray(source)) throw new TypeError("members must be an array");
+  if (!Number.isInteger(maxMembers) || maxMembers < 0) throw new TypeError("maxMembers must be a non-negative integer");
+  const members = source.map((member) => {
+    if (!member || typeof member !== "object" || Array.isArray(member)) throw new TypeError("members must contain objects");
+    return copy(member);
+  });
+  members.sort((left, right) => {
+    const leftRef = String(refOf(left));
+    const rightRef = String(refOf(right));
+    const byRef = leftRef < rightRef ? -1 : leftRef > rightRef ? 1 : 0;
+    if (byRef) return byRef;
+    const leftVersion = String(versionOf(left));
+    const rightVersion = String(versionOf(right));
+    const byVersion = leftVersion < rightVersion ? -1 : leftVersion > rightVersion ? 1 : 0;
+    if (byVersion) return byVersion;
+    const leftCanonical = canonicalize(left);
+    const rightCanonical = canonicalize(right);
+    return leftCanonical < rightCanonical ? -1 : leftCanonical > rightCanonical ? 1 : 0;
+  });
+  return { members: members.slice(0, maxMembers), truncated: members.length > maxMembers };
+}
+
+function snapshotIdentity(payload, stableRef, recordKind) {
+  const versionPayload = {
+    schema_version: "1.0",
+    record_kind: recordKind,
+    stable_ref: stableRef,
+    ...payload,
+  };
+  const digest = hashCanonical(versionPayload);
+  return {
+    version_id: `${stableRef}@${digest}`,
+    sha256: digest,
+    cache_key: `${stableRef}@${digest}`,
+  };
+}
+
+/** Build a bounded, immutable, source-preserving retrieval view. */
+export function buildViewSnapshot(input) {
+  const source = objectInput(input, "buildViewSnapshot");
+  const rawView = pick(source, "view_spec", "viewSpec") ?? {};
+  const viewSpec = copy(rawView);
+  const stableRef = pick(source, "snapshot_ref", "snapshotRef")
+    ?? pick(viewSpec, "stable_ref", "stableRef")
+    ?? "sg:view/snapshot";
+  const canonicalStableRef = createStableRef(stableRef);
+  const requestedLimit = pick(source, "max_members", "maxMembers", "limit");
+  const maxMembers = requestedLimit === undefined ? 256 : Number(requestedLimit);
+  if (!Number.isInteger(maxMembers) || maxMembers < 0) throw new TypeError("maxMembers must be a non-negative integer");
+  const normalized = normalizeMembers(pick(source, "members", "entries", "items"), maxMembers);
+  const payload = {
+    as_of: pick(source, "as_of", "asOf"),
+    builder_version: pick(source, "builder_version", "builderVersion") ?? "retriever@1",
+    heads: sortedUniqueStrings(pick(source, "heads", "event_heads", "eventHeads")),
+    members: normalized.members,
+    policy: copy(pick(source, "policy", "policy_ref", "policyRef")),
+    snapshot_ref: canonicalStableRef,
+    truncated: normalized.truncated,
+    transaction_at: pick(source, "transaction_at", "transactionAt", "transaction_watermark", "transactionWatermark"),
+    valid_at: pick(source, "valid_at", "validAt", "valid_watermark", "validWatermark"),
+    view_spec: viewSpec,
+  };
+  for (const [key, value] of Object.entries(payload)) if (value === undefined) delete payload[key];
+  const supplied = pick(source, "version_id", "versionId");
+  const identity = snapshotIdentity(payload, canonicalStableRef, "view_snapshot");
+  if (supplied !== undefined && supplied !== identity.version_id) throw new TypeError("snapshot version_id does not match content");
+  return canonicalFreeze({ schema_version: "1.0", record_kind: "view_snapshot", stable_ref: canonicalStableRef, ...payload, ...identity });
+}
+
+export const createViewSnapshot = buildViewSnapshot;
+
+function estimateTokens(member) {
+  const text = pick(member, "content", "text", "summary") ?? canonicalize(member);
+  return Math.max(1, Math.ceil(String(text).length / 4));
+}
+
+/** Build a deterministic, budget-bounded context package linked to a snapshot. */
+export function buildContextPackage(input) {
+  const source = objectInput(input, "buildContextPackage");
+  const snapshot = pick(source, "snapshot");
+  const view = snapshot && typeof snapshot === "object"
+    ? snapshot
+    : buildViewSnapshot({ ...source, viewSpec: { stableRef: "sg:view/context" } });
+  const suppliedMembers = pick(source, "members", "entries", "items") ?? pick(view, "members", "entries", "items") ?? [];
+  const normalized = normalizeMembers(suppliedMembers, Number(pick(source, "max_members", "maxMembers") ?? 256));
+  const budgetInput = pick(source, "budget") ?? {};
+  const tokenBudget = Number(typeof budgetInput === "number" ? budgetInput : pick(budgetInput, "tokens", "token_budget", "tokenBudget") ?? 0);
+  if (!Number.isInteger(tokenBudget) || tokenBudget < 0) throw new TypeError("budget.tokens must be a non-negative integer");
+  let usedTokens = 0;
+  const members = [];
+  for (const member of normalized.members) {
+    const cost = estimateTokens(member);
+    if (usedTokens + cost > tokenBudget) break;
+    members.push(member);
+    usedTokens += cost;
+  }
+  const payload = {
+    budget: { tokens: tokenBudget, used_tokens: usedTokens, truncated: members.length < normalized.members.length },
+    members,
+    member_refs: members.map(memberReference).filter((member) => Object.keys(member).length > 0),
+    member_manifest: members.map(memberReference).filter((member) => Object.keys(member).length > 0),
+    policy: copy(pick(source, "policy", "policy_ref", "policyRef") ?? pick(view, "policy", "policy_ref", "policyRef")),
+    query: pick(source, "query"),
+    query_class: pick(source, "query_class", "queryClass"),
+    retriever: pick(source, "retriever"),
+    selectors: copy(pick(source, "selectors", "selector")),
+    snapshot: pick(view, "version_id", "versionId") ?? pick(view, "snapshot_ref", "snapshotRef", "stable_ref", "stableRef"),
+    snapshot_ref: pick(view, "snapshot_ref", "snapshotRef", "stable_ref", "stableRef"),
+    snapshot_version_id: pick(view, "version_id", "versionId"),
+    assembly_receipt: copy(pick(source, "assembly_receipt", "assemblyReceipt")),
+  };
+  for (const [key, value] of Object.entries(payload)) if (value === undefined) delete payload[key];
+  const stableRef = pick(source, "context_ref", "contextRef") ?? "sg:view/context";
+  const canonicalStableRef = createStableRef(stableRef);
+  const identity = snapshotIdentity(payload, canonicalStableRef, "context_package");
+  return canonicalFreeze({ schema_version: "1.0", record_kind: "context_package", stable_ref: canonicalStableRef, ...payload, ...identity });
+}
+
+export const createContextPackage = buildContextPackage;

package/scripts/agent-native/self-description.mjs

@@ -0,0 +1,160 @@
+import crypto from "node:crypto";
+import { deepFreeze, hashCanonical } from "./canonical-json.mjs";
+import { createVersionId } from "./identity.mjs";
+
+export const AGENT_REF = "sg:agent/stylegallery";
+export const CONFORMANCE_PROFILE_REF = "sg:profile/agent-native-read-conformance";
+
+export class SelfDescriptionError extends TypeError {
+  constructor(code, message) {
+    super(message);
+    this.name = "SelfDescriptionError";
+    this.code = code;
+  }
+}
+
+function fail(code, message) {
+  throw new SelfDescriptionError(code, message);
+}
+
+function byRef(fixture, stableRef) {
+  const record = fixture.records.find((item) => item.stable_ref === stableRef);
+  if (!record) fail("self_description_record_missing", `required fixture record ${stableRef} is missing`);
+  return record;
+}
+
+function sha256(value) {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+function receiptVersion(receipt) {
+  const payload = { ...receipt };
+  delete payload.version_id;
+  delete payload.versionId;
+  return createVersionId({ stableRef: receipt.stable_ref, payload });
+}
+
+/**
+ * Verify an execution receipt without executing its command again.  The
+ * receipt is an immutable, content-addressed observation: its fixture source
+ * VersionID, command, normalized result digest, and independent verifier are
+ * all checked before a conformance claim can be projected as verified.
+ */
+export function verifyConformanceReceipt({ fixture, receipt, source }) {
+  if (!receipt || receipt.record_kind !== "execution_receipt") {
+    fail("self_description_receipt_kind_invalid", "conformance evidence must be an execution receipt");
+  }
+  if (!source || source.record_kind !== "executable_fixture") {
+    fail("self_description_receipt_source_invalid", "execution receipt must reference an executable fixture");
+  }
+  if (receipt.fixture_ref !== fixture.fixture_ref) {
+    fail("self_description_receipt_fixture_mismatch", "execution receipt fixture_ref does not match the loaded fixture");
+  }
+  if (receipt.fixture_record_ref !== source.stable_ref || receipt.fixture_version_id !== source.version_id) {
+    fail("self_description_receipt_version_mismatch", "execution receipt is not bound to the executable fixture VersionID");
+  }
+  if (receipt.command !== source.command) {
+    fail("self_description_receipt_command_mismatch", "execution receipt command does not match the executable fixture");
+  }
+  const result = receipt.result;
+  if (!result || typeof result !== "object" || Array.isArray(result)) {
+    fail("self_description_receipt_result_invalid", "execution receipt must contain a normalized result object");
+  }
+  if (result.exit_code !== source.expected?.exit_code || result.report_ok !== source.expected?.report_ok) {
+    fail("self_description_receipt_result_mismatch", "execution receipt result does not match fixture expectations");
+  }
+  const expectedStderrHash = sha256(String(source.expected?.stderr ?? ""));
+  if (result.stderr_sha256 !== expectedStderrHash) {
+    fail("self_description_receipt_stderr_mismatch", "execution receipt stderr digest does not match fixture expectations");
+  }
+  if (typeof result.stderr_sha256 !== "string" || !/^[a-f0-9]{64}$/.test(result.stderr_sha256)) {
+    fail("self_description_receipt_digest_invalid", "execution receipt stderr digest must be lowercase sha256 hex");
+  }
+  if (receipt.result_sha256 !== hashCanonical(result)) {
+    fail("self_description_receipt_result_digest_mismatch", "execution receipt result_sha256 does not match canonical result bytes");
+  }
+  if (receipt.version_id !== receiptVersion(receipt)) {
+    fail("self_description_receipt_version_digest_mismatch", "execution receipt VersionID does not match immutable receipt bytes");
+  }
+  const verification = receipt.verification;
+  if (!verification || verification.status !== "PASS" || verification.method !== "captured-command-result") {
+    fail("self_description_receipt_unverified", "execution receipt must carry a PASS captured-command verification");
+  }
+  const verifier = fixture.records.find((record) => record.stable_ref === verification.verifier_ref);
+  if (!verifier || verifier.record_kind !== "validator" || verifier.validator_version !== verification.verifier_version) {
+    fail("self_description_receipt_verifier_invalid", "execution receipt verifier is not a fixture validator version");
+  }
+  return deepFreeze({ receipt, source, verifier });
+}
+
+function conformanceClaims(fixture, profile) {
+  const refs = Array.isArray(profile.claim_refs) ? profile.claim_refs : [];
+  return refs.map((claimRef) => {
+    const claim = byRef(fixture, claimRef);
+    const evidence = fixture.records.filter((record) => record.record_kind === "evidence_link" && record.claim_ref === claimRef);
+    const sources = evidence.map((link) => byRef(fixture, link.source_ref));
+    if (sources.length === 0 || sources.some((source) => source.record_kind !== "executable_fixture")) {
+      fail("self_description_evidence_not_executable", `conformance claim ${claimRef} must point only at executable fixture evidence`);
+    }
+    const validations = fixture.records.filter((record) => record.record_kind === "validation_report" && record.claim_ref === claimRef);
+    const execution_receipts = sources.map((source) => {
+      const receipts = fixture.records.filter((record) => record.record_kind === "execution_receipt" && record.fixture_record_ref === source.stable_ref);
+      if (receipts.length !== 1) {
+        fail("self_description_execution_receipt_missing", `conformance source ${source.stable_ref} must have exactly one immutable execution receipt`);
+      }
+      return verifyConformanceReceipt({ fixture, receipt: receipts[0], source });
+    });
+    return { claim, evidence, executable_sources: sources, execution_receipts, validations };
+  });
+}
+
+function operationSummary(operation) {
+  return {
+    adapters: operation.adapters,
+    effect_class: operation.effect_class,
+    idempotent: operation.idempotent,
+    name: operation.name,
+    read_only: operation.read_only,
+    stable_ref: operation.stable_ref,
+    version_id: operation.version_id,
+  };
+}
+
+export function createSelfDescription({ fixture, operations }) {
+  if (!fixture || !Array.isArray(fixture.records) || !fixture.manifest) {
+    fail("self_description_fixture_invalid", "self-description requires an immutable fixture");
+  }
+  if (!Array.isArray(operations)) fail("self_description_operations_invalid", "operations must be an array");
+  const agent = byRef(fixture, AGENT_REF);
+  const conformanceProfile = byRef(fixture, CONFORMANCE_PROFILE_REF);
+  if (conformanceProfile.conformance_level !== "fixture_verified") {
+    fail("self_description_profile_unverified", "conformance profile must declare fixture_verified only after receipt verification");
+  }
+  const summaries = operations.map(operationSummary).sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
+  return deepFreeze({
+    agent,
+    conformance: {
+      claims: conformanceClaims(fixture, conformanceProfile),
+      profile: conformanceProfile,
+      status: "fixture_verified",
+    },
+    manifest: {
+      entry_count: fixture.manifest.entries.length,
+      manifest_ref: fixture.manifest.manifest_ref,
+      sha256: fixture.manifest.sha256,
+      version_id: fixture.manifest.version_id,
+    },
+    operation_digest: hashCanonical(summaries),
+    operations: summaries,
+    protocol_surfaces: {
+      a2a: { mode: "task_projection", protocol: "A2A v1" },
+      ag_ui: { mode: "event_projection", protocol: "AG-UI 0.0.57" },
+      cli: { commands: summaries.filter((item) => item.adapters.includes("cli")).map((item) => item.name), format: "json" },
+      mcp: { mode: "read_only", operations: summaries.filter((item) => item.read_only).map((item) => item.name), protocol: "MCP v1" },
+    },
+    schema_version: "1.0",
+  });
+}
+
+export const describeAgentNative = createSelfDescription;
+export const createConformanceProfile = createSelfDescription;

package/scripts/artifact-metadata.mjs

@@ -0,0 +1,20 @@
+import crypto from "node:crypto";
+
+const pngSignature = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+
+function pngDimensions(bytes) {
+  if (bytes.length < 24 || !bytes.subarray(0, 8).equals(pngSignature) || bytes.toString("ascii", 12, 16) !== "IHDR") return undefined;
+  const width = bytes.readUInt32BE(16);
+  const height = bytes.readUInt32BE(20);
+  return width > 0 && height > 0 ? { height, width } : undefined;
+}
+
+export function artifactMetadata(bytes, mediaType) {
+  const metadata = {
+    byte_length: bytes.length,
+    media_type: mediaType,
+    sha256: `sha256:${crypto.createHash("sha256").update(bytes).digest("hex")}`,
+  };
+  if (mediaType === "image/png") Object.assign(metadata, pngDimensions(bytes));
+  return metadata;
+}