@warpgogol/werkstatt-shared 0.2.0

package/src/share/agent/knowledge.ts

@@ -0,0 +1,96 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+RFC-0287: the static Agent Surface knowledge tier. Defines the closed domain
+list, the per-domain envelope shape, and the pure envelope formatter. Callers
+(kernel commands) load and project business content through the existing
+RFC-0148 projectors and pass the already-resolved per-language payload here —
+this module never reads files or invents fact shapes.
+</purpose>
+<non-goals>
+  <item>Do not read content or call projectors — the kernel command does that.</item>
+  <item>Do not define new fact shapes — extend business-projection.ts/models.ts first.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0287: initial knowledge tier — domain list, envelope, formatter.</item>
+  <item>RFC-0602: allow null lastVerified in AgentKnowledgeFreshness for derived-source fallback.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { computeAgentManifestContentHash } from "./manifest.ts";
+import type { AgentSurfaceProof } from "./proof.ts";
+
+/** Exactly the `public`-visibility keys of BUSINESS_DOMAIN_VISIBILITY (RFC-0148). */
+export const AGENT_KNOWLEDGE_DOMAINS = [
+  "company",
+  "legal",
+  "contact",
+  "offer",
+  "service",
+  "location",
+  "web",
+  "people",
+  "trust",
+  "faq",
+] as const;
+
+export type AgentKnowledgeDomain = (typeof AGENT_KNOWLEDGE_DOMAINS)[number];
+
+export function isAgentKnowledgeDomain(value: string): value is AgentKnowledgeDomain {
+  return (AGENT_KNOWLEDGE_DOMAINS as readonly string[]).includes(value);
+}
+
+export interface AgentKnowledgeFreshness {
+  lastVerified: string | null;
+  source: "ckl-claim-ledger" | "authored-verification" | "derived-source";
+  coverage: "domain";
+}
+
+export interface AgentKnowledgeEnvelope<TData = unknown> {
+  /** e.g. "gogol.agent.knowledge/offer@1" or @2 for RFC-0319 shape changes. */
+  schema: string;
+  site: string;
+  baseUrl: string;
+  languages: { default: string; supported: string[] };
+  /** sha256 hex over sorted-key JSON of this document minus contentHash. */
+  contentHash: string;
+  /** RFC-0319: required freshness for every emitted envelope. */
+  freshness?: AgentKnowledgeFreshness;
+  /** Per-language payload; non-default languages carry only overlay fields (RFC-0008). */
+  data: Record<string, TData>;
+  /** RFC-0308: detached Ed25519 proof, null/absent when unsigned. */
+  proof?: AgentSurfaceProof | null;
+}
+
+export interface AgentKnowledgeBuildInput<TData = unknown> {
+  domain: AgentKnowledgeDomain;
+  site: string;
+  baseUrl: string;
+  languages: { default: string; supported: string[] };
+  /** Already-projected per-language payload — never raw content. */
+  data: Record<string, TData>;
+  freshness?: AgentKnowledgeFreshness;
+  /** RFC-0319: schema version. Defaults to 1. Bump to 2 for breaking shape changes. */
+  schemaVersion?: number;
+}
+
+/** Pure: assemble + hash one domain's knowledge envelope. Deterministic. */
+export function formatAgentKnowledge<TData = unknown>(
+  input: AgentKnowledgeBuildInput<TData>,
+): AgentKnowledgeEnvelope<TData> {
+  const version = input.schemaVersion ?? 1;
+  const base: Omit<AgentKnowledgeEnvelope<TData>, "contentHash"> = {
+    schema: `gogol.agent.knowledge/${input.domain}@${version}`,
+    site: input.site,
+    baseUrl: input.baseUrl.replace(/\/+$/, ""),
+    languages: {
+      default: input.languages.default,
+      supported: [...input.languages.supported].sort(),
+    },
+    ...(input.freshness ? { freshness: input.freshness } : {}),
+    data: input.data,
+  };
+  const contentHash = computeAgentManifestContentHash(base as unknown as Record<string, unknown>);
+  return { ...base, contentHash };
+}

package/src/share/agent/manifest.ts

@@ -0,0 +1,126 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+RFC-0286: the Agent Surface Manifest — the single generated artifact every
+protocol projection (knowledge files, OpenAPI, MCP) derives from (AS-1). Pure,
+deterministic assembly: no I/O, no timestamps, sorted-key canonical hashing so
+two runs on unchanged input are byte-identical (AS-7).
+</purpose>
+<non-goals>
+  <item>Do not read files or content — callers (kernel commands) load and pass data.</item>
+  <item>Do not sign — proof is always null here; RFC-0308 adds signing over the
+        domain-separated content hash payload via agent.surface.sign.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0286: initial manifest contract and pure builder.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { createHash } from "node:crypto";
+import type { AgentSurfaceProof } from "./proof.ts";
+
+/** Semver of THIS manifest schema. Bump only via an RFC amending RFC-0286 (AS-7). */
+export const AGENT_SURFACE_VERSION = "1.0.0";
+
+export interface AgentKnowledgeRef {
+  /** A BusinessDomain with visibility "public" (RFC-0287). */
+  domain: string;
+  url: string;
+  /** e.g. "gogol.agent.knowledge/offer@1". */
+  schema: string;
+}
+
+export interface AgentActionRef {
+  /** Capability catalog id, e.g. "lead.submit" (RFC-0288). */
+  id: string;
+  url: string;
+  title: Record<string, string>;
+  inputSchemaRef: string;
+  entitlement: "agent.actions";
+}
+
+export interface AgentSurfaceManifest {
+  surfaceVersion: string;
+  site: string;
+  baseUrl: string;
+  languages: { default: string; supported: string[] };
+  /** sha256 hex over sorted-key JSON of this document minus contentHash + proof. */
+  contentHash: string;
+  knowledge: AgentKnowledgeRef[];
+  actions: AgentActionRef[];
+  interfaces: {
+    llms: string;
+    twins: { pattern: string } | null;
+    openapi: string | null;
+    mcp: { url: string; protocolVersion: string } | null;
+  };
+  /** Null until agent.surface.sign signs it (RFC-0308) or when no key material exists. */
+  proof: AgentSurfaceProof | null;
+}
+
+export interface AgentSurfaceManifestInput {
+  site: string;
+  baseUrl: string;
+  languages: { default: string; supported: string[] };
+  knowledge?: AgentKnowledgeRef[];
+  actions?: AgentActionRef[];
+  hasTwins?: boolean;
+  openapiUrl?: string | null;
+  mcp?: { url: string; protocolVersion: string } | null;
+}
+
+// ---------------------------------------------------------------------------
+// Canonicalization — shared by hashing here and by signing in RFC-0308
+// ---------------------------------------------------------------------------
+
+function sortKeysDeep(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sortKeysDeep);
+  if (value !== null && typeof value === "object") {
+    const out: Record<string, unknown> = {};
+    for (const key of Object.keys(value as Record<string, unknown>).sort()) {
+      out[key] = sortKeysDeep((value as Record<string, unknown>)[key]);
+    }
+    return out;
+  }
+  return value;
+}
+
+/** Deterministic sorted-key JSON serialization — no whitespace, stable key order. */
+export function canonicalJson(value: unknown): string {
+  return JSON.stringify(sortKeysDeep(value));
+}
+
+/** sha256 hex over the canonical JSON of `doc` with `contentHash` and `proof` removed. */
+export function computeAgentManifestContentHash(doc: Record<string, unknown>): string {
+  const { contentHash: _contentHash, proof: _proof, ...rest } = doc;
+  return createHash("sha256").update(canonicalJson(rest), "utf8").digest("hex");
+}
+
+// ---------------------------------------------------------------------------
+// Builder
+// ---------------------------------------------------------------------------
+
+/** Pure: assemble + hash the manifest. Deterministic — sorts refs and languages. */
+export function buildAgentSurfaceManifest(input: AgentSurfaceManifestInput): AgentSurfaceManifest {
+  const base: Omit<AgentSurfaceManifest, "contentHash"> = {
+    surfaceVersion: AGENT_SURFACE_VERSION,
+    site: input.site,
+    baseUrl: input.baseUrl.replace(/\/+$/, ""),
+    languages: {
+      default: input.languages.default,
+      supported: [...input.languages.supported].sort(),
+    },
+    knowledge: [...(input.knowledge ?? [])].sort((a, b) => a.domain.localeCompare(b.domain)),
+    actions: [...(input.actions ?? [])].sort((a, b) => a.id.localeCompare(b.id)),
+    interfaces: {
+      llms: "/llms.txt",
+      twins: input.hasTwins ? { pattern: "/**.md" } : null,
+      openapi: input.openapiUrl ?? null,
+      mcp: input.mcp ?? null,
+    },
+    proof: null,
+  };
+  const contentHash = computeAgentManifestContentHash(base as unknown as Record<string, unknown>);
+  return { ...base, contentHash };
+}

package/src/share/agent/mcp-card.ts

@@ -0,0 +1,63 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+RFC-0783: pure, dependency-free formatter that projects a site's Agent Surface
+Manifest into a SEP-1649 MCP Server Card for /.well-known/mcp/server-card.json.
+No I/O — the kernel command loads the manifest and passes it here.
+</purpose>
+<non-goals>
+  <item>Do not read files — callers load and pass the manifest.</item>
+  <item>Do not sign — signing is a separate concern (agent.surface.sign).</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0783: initial MCP Server Card projection.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type { AgentSurfaceManifest } from "./manifest.ts";
+
+/** SEP-1649 MCP Server Card. */
+export interface McpServerCard {
+  serverInfo: {
+    name: string;
+    version: string;
+    description?: string;
+  };
+  transport: {
+    type: "streamable-http";
+    url: string;
+  };
+  protocolVersion: string;
+  capabilities: {
+    tools: { listChanged: boolean };
+    resources: { listChanged: boolean; subscribe: boolean };
+    prompts: { listChanged: boolean };
+  };
+}
+
+/**
+ * Pure: project Agent Surface Manifest into SEP-1649 server card.
+ * Deterministic — same manifest input produces byte-identical output (DNA-58).
+ * Returns null when manifest.interfaces.mcp is null (no MCP endpoint).
+ */
+export function buildMcpServerCard(manifest: AgentSurfaceManifest): McpServerCard | null {
+  if (!manifest.interfaces.mcp) return null;
+
+  return {
+    serverInfo: {
+      name: `${manifest.site}-agent-gate`,
+      version: manifest.surfaceVersion,
+    },
+    transport: {
+      type: "streamable-http",
+      url: manifest.interfaces.mcp.url,
+    },
+    protocolVersion: manifest.interfaces.mcp.protocolVersion,
+    capabilities: {
+      tools: { listChanged: false },
+      resources: { listChanged: false, subscribe: false },
+      prompts: { listChanged: false },
+    },
+  };
+}

package/src/share/agent/omit-empty.ts

@@ -0,0 +1,77 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+RFC-0319: omit-empty serialization for agent knowledge JSON envelopes.
+Prunes empty strings, empty objects, and empty arrays from public knowledge
+payloads before hashing and serialization. Never omits false, 0, or null
+when schema explicitly allows them.
+</purpose>
+<non-goals>
+  <item>Do not omit false, 0, or null when schema allows them.</item>
+  <item>Do not invent values to fill empty fields.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0319: initial implementation.</item>
+</CHANGE_SUMMARY>
+*/
+
+export interface OmitEmptyOptions {
+  /** JSON pointer paths where empty arrays are meaningful and should be preserved. */
+  preserveEmptyArraysFor?: readonly string[];
+  /** JSON pointer paths where empty objects are meaningful and should be preserved. */
+  preserveEmptyObjectsFor?: readonly string[];
+}
+
+/**
+ * RFC-0319: Recursively prune empty strings, empty objects, and empty arrays.
+ * Returns `undefined` if the entire value becomes empty after pruning.
+ */
+export function omitEmptyKnowledgeValues<T>(
+  value: T,
+  opts: OmitEmptyOptions = {},
+  path = "",
+): T | undefined {
+  if (value === null || value === undefined) return undefined;
+
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    return trimmed === "" ? undefined : (value as T);
+  }
+
+  if (typeof value === "boolean" || typeof value === "number") {
+    return value;
+  }
+
+  if (Array.isArray(value)) {
+    const pruned = value
+      .map((item, i) => omitEmptyKnowledgeValues(item, opts, `${path}/${i}`))
+      .filter((item) => item !== undefined);
+
+    if (pruned.length === 0) {
+      const preserve = opts.preserveEmptyArraysFor?.includes(path);
+      return preserve ? ([] as unknown as T) : undefined;
+    }
+    return pruned as unknown as T;
+  }
+
+  if (typeof value === "object") {
+    const result: Record<string, unknown> = {};
+    for (const [key, val] of Object.entries(value as Record<string, unknown>)) {
+      const childPath = `${path}/${key}`;
+      const pruned = omitEmptyKnowledgeValues(val, opts, childPath);
+      if (pruned !== undefined) {
+        result[key] = pruned;
+      }
+    }
+
+    const keys = Object.keys(result);
+    if (keys.length === 0) {
+      const preserve = opts.preserveEmptyObjectsFor?.includes(path);
+      return preserve ? ({} as unknown as T) : undefined;
+    }
+    return result as unknown as T;
+  }
+
+  return value;
+}

package/src/share/agent/openapi.ts

@@ -0,0 +1,157 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+RFC-0289: pure, dependency-free formatter that projects a site's Agent Surface
+Manifest (+ the capability schemas for its active actions) into a static
+OpenAPI 3.1 document. No transformation of capability schemas — they are
+copied verbatim (AGO-04 enforces this).
+</purpose>
+<non-goals>
+  <item>Do not read files or resolve capabilities — the kernel command does that
+        and passes the manifest + capability schemas here.</item>
+  <item>Do not adopt an OpenAPI library/types package — this is a small, closed
+        structural subset (AS-5: protocols are disposable).</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0289: initial OpenAPI projection.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type { AgentSurfaceManifest } from "./manifest.ts";
+import type { CapabilityInputOutputSchema } from "@warpgogol/werkstatt-shared/ontology";
+
+export interface OpenApiSchemaObject {
+  type: string;
+  required?: string[];
+  additionalProperties?: boolean;
+  properties?: Record<string, unknown>;
+  description?: string;
+}
+
+export interface OpenApiOperation {
+  operationId: string;
+  summary?: string;
+  tags: string[];
+  requestBody?: {
+    required: true;
+    content: { "application/json": { schema: OpenApiSchemaObject } };
+  };
+  responses: Record<
+    string,
+    { description: string; content?: { "application/json": { schema: unknown } } }
+  >;
+}
+
+export interface OpenApiDocument {
+  openapi: "3.1.0";
+  info: { title: string; version: string; "x-gogol-content-hash": string };
+  servers: Array<{ url: string }>;
+  paths: Record<string, Record<string, OpenApiOperation>>;
+  components: { schemas: Record<string, unknown> };
+  externalDocs?: { url: string; description: string };
+  "x-gogol-mcp"?: { url: string; protocolVersion: string };
+  "x-gogol-proof"?: unknown;
+}
+
+/** One active capability's schemas — the exact shapes referenced by its AgentActionRef. */
+export interface CapabilitySchemaInput {
+  id: string;
+  input: CapabilityInputOutputSchema;
+  output: CapabilityInputOutputSchema;
+}
+
+/** Generic envelope schema — every knowledge domain shares this wrapper shape (RFC-0287); only `data`'s inner shape varies by domain and is intentionally left untyped here. */
+function knowledgeEnvelopeSchema(): OpenApiSchemaObject {
+  return {
+    type: "object",
+    required: ["schema", "site", "baseUrl", "languages", "contentHash", "data"],
+    properties: {
+      schema: { type: "string" },
+      site: { type: "string" },
+      baseUrl: { type: "string" },
+      languages: { type: "object" },
+      contentHash: { type: "string" },
+      freshness: { type: "object" },
+      data: { type: "object", description: "Per-language payload; shape varies by domain." },
+    },
+  };
+}
+
+/**
+ * Pure: project the manifest (+ active capabilities' schemas) into an OpenAPI
+ * 3.1 document. Exhaustive per the RFC-0289 projection table — adds nothing beyond it.
+ */
+export function formatAgentOpenApi(
+  manifest: AgentSurfaceManifest,
+  capabilitySchemas: CapabilitySchemaInput[],
+): OpenApiDocument {
+  const schemasById = new Map(capabilitySchemas.map((c) => [c.id, c]));
+  const paths: OpenApiDocument["paths"] = {};
+  const componentSchemas: Record<string, unknown> = {};
+
+  for (const ref of manifest.knowledge) {
+    componentSchemas[`knowledge-${ref.domain}`] = knowledgeEnvelopeSchema();
+    paths[ref.url] = {
+      get: {
+        operationId: `knowledge.${ref.domain}.get`,
+        tags: ["knowledge"],
+        responses: {
+          "200": {
+            description: `${ref.domain} knowledge envelope`,
+            content: {
+              "application/json": {
+                schema: { $ref: `#/components/schemas/knowledge-${ref.domain}` },
+              },
+            },
+          },
+        },
+      },
+    };
+  }
+
+  for (const ref of manifest.actions) {
+    const schemas = schemasById.get(ref.id);
+    if (!schemas) continue; // defensive — AGO-04-checked at validate time
+    componentSchemas[`${ref.id}-input`] = schemas.input;
+    componentSchemas[`${ref.id}-output`] = schemas.output;
+    paths[ref.url] = {
+      post: {
+        operationId: `action.${ref.id}`,
+        summary: ref.title[manifest.languages.default] ?? ref.id,
+        tags: ["actions"],
+        requestBody: {
+          required: true,
+          content: { "application/json": { schema: schemas.input } },
+        },
+        responses: {
+          "200": {
+            description: `${ref.id} accepted`,
+            content: { "application/json": { schema: schemas.output } },
+          },
+          "400": { description: "Schema violation" },
+          "429": { description: "Rate limit exceeded" },
+        },
+      },
+    };
+  }
+
+  const doc: OpenApiDocument = {
+    openapi: "3.1.0",
+    info: {
+      title: `${manifest.site} agent surface`,
+      version: manifest.surfaceVersion,
+      "x-gogol-content-hash": manifest.contentHash,
+    },
+    servers: [{ url: manifest.baseUrl }],
+    paths,
+    components: { schemas: componentSchemas },
+    externalDocs: {
+      url: `${manifest.baseUrl}${manifest.interfaces.llms}`,
+      description: "LLM-oriented text surface",
+    },
+  };
+  if (manifest.interfaces.mcp) doc["x-gogol-mcp"] = manifest.interfaces.mcp;
+  if (manifest.proof) doc["x-gogol-proof"] = manifest.proof;
+  return doc;
+}

package/src/share/agent/proof.ts

@@ -0,0 +1,61 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+RFC-0308: pure, framework-free Ed25519 proof types and domain-separated
+signing payload builder for Agent Surface artifacts. The signing and
+verification primitives (Ed25519 sign/verify, multibase encoding) live in
+@warpgogol/werkstatt-shared/passport; this module owns only the canonical payload format and
+the proof shape that generators, agent.surface.sign, and agent.surface.verify
+share.
+</purpose>
+<non-goals>
+  <item>Do not import or call Ed25519 signing/verification primitives — that
+        is @warpgogol/werkstatt-shared/passport's job. This module is pure and dependency-free.</item>
+  <item>Do not read files or perform I/O.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0308: initial proof module — payload builder + proof type.</item>
+</CHANGE_SUMMARY>
+*/
+
+/** Artifact kind for domain-separated signing (RFC-0308). */
+export type AgentProofArtifactKind = "manifest" | "knowledge" | "openapi";
+
+/**
+ * W3C Ed25519Signature2020 proof object embedded in signed agent artifacts.
+ *
+ * `proofValue` is a multibase base58btc-encoded Ed25519 signature (prefix "z"),
+ * consistent with the Cosmic Passport key encoding (RFC-0028).
+ */
+export interface AgentSurfaceProof {
+  type: "Ed25519Signature2020";
+  created: string;
+  verificationMethod: string;
+  proofPurpose: "assertionMethod";
+  /** Multibase-encoded (base58btc, prefix "z") Ed25519 signature. */
+  proofValue: string;
+}
+
+/** Domain-separation prefix for agent surface signing payloads (RFC-0308). */
+export const AGENT_PROOF_DOMAIN = "WARPGOGOL_AGENT_SURFACE_V1";
+
+/**
+ * Build the domain-separated canonical signing payload for an agent surface
+ * artifact.
+ *
+ * The signed input is:
+ * ```
+ * WARPGOGOL_AGENT_SURFACE_V1\n<artifact-kind>\n<absolute-canonical-url>\n<contentHash>
+ * ```
+ *
+ * This prevents signature reuse across artifact kinds or URLs.
+ */
+export function buildAgentSigningPayload(
+  kind: AgentProofArtifactKind,
+  canonicalUrl: string,
+  contentHash: string,
+): Uint8Array {
+  const text = `${AGENT_PROOF_DOMAIN}\n${kind}\n${canonicalUrl}\n${contentHash}`;
+  return new TextEncoder().encode(text);
+}

package/src/share/attribution-display.ts

@@ -0,0 +1,86 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+  RFC-0231 attribution visibility policy. One vocabulary + one pure resolver that
+  decides whether an attribution surface (material credit, prose byline, footer
+  copyright) renders its VISIBLE form. Hiding never affects provenance: callers
+  must keep emitting JSON-LD and the credits-page listing regardless of the result.
+</purpose>
+<non-goals>
+  <item>Do not read content or globs; callers pass the resolved overrides.</item>
+  <item>Do not render UI or emit JSON-LD; @warpgogol/werkstatt-site/ui owns presentation.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0231: initial attribution visibility policy resolver + site schema.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { z } from "zod";
+
+/** RFC-0231: every visibility level speaks the same two-word vocabulary. */
+export type AttributionDisplay = "shown" | "hidden";
+export type AttributionSurface = "material-credit" | "prose-authorship" | "footer-copyright";
+/** Site default may defer to RFC-0228 editorial/decorative intent. */
+export type AttributionSiteDefault = "byIntent" | "shown" | "hidden";
+
+export const attributionDisplaySchema = z.enum(["shown", "hidden"]);
+export const attributionSiteDefaultSchema = z.enum(["byIntent", "shown", "hidden"]);
+
+/** RFC-0231: the `attribution` block authored in site/{lang}/labels.md. */
+export const attributionPolicySchema = z
+  .object({
+    /** Material-credit inline disclosures. Defaults to byIntent. */
+    credits: attributionSiteDefaultSchema.optional(),
+    /** Visible prose byline. Defaults to shown. */
+    proseAuthorship: attributionDisplaySchema.optional(),
+    /** Footer site-copyright line. Defaults to shown. */
+    footerCopyright: attributionDisplaySchema.optional(),
+  })
+  .strict();
+export type AttributionPolicy = z.infer<typeof attributionPolicySchema>;
+
+export interface AttributionDisplayInputs {
+  surface: AttributionSurface;
+  /** RFC-0228 intent of the target; editorial ⇒ shown, decorative ⇒ hidden under byIntent. */
+  intent?: "editorial" | "decorative";
+  /** Level 1: per-asset `display` in the sidecar (material credit only). */
+  assetOverride?: AttributionDisplay;
+  /** Level 2: per-placement `creditDisplay` on the section/block content. */
+  placementOverride?: AttributionDisplay;
+  /** Level 3: per-page `attribution.*` in page frontmatter. */
+  pageOverride?: AttributionDisplay;
+  /** Level 4: site default from the `attribution` labels block. */
+  siteDefault?: AttributionSiteDefault;
+}
+
+/**
+ * RFC-0231: resolve one visible-surface decision. Most-specific level wins; the
+ * intrinsic default (editorial shown / decorative hidden) applies only when no
+ * explicit level set a value and the site default is `byIntent` (or unset).
+ */
+export function resolveAttributionDisplay(inputs: AttributionDisplayInputs): AttributionDisplay {
+  const explicit = inputs.assetOverride ?? inputs.placementOverride ?? inputs.pageOverride;
+  if (explicit) return explicit;
+
+  const site = inputs.siteDefault ?? "byIntent";
+  if (site === "shown" || site === "hidden") return site;
+
+  // byIntent: decorative material is quiet by default; everything else shows.
+  return inputs.intent === "decorative" ? "hidden" : "shown";
+}
+
+/** RFC-0231: parse the optional site `attribution` block; tolerate absence/garbage. */
+export function readAttributionPolicy(
+  labels: Record<string, unknown> | undefined,
+): AttributionPolicy {
+  const parsed = attributionPolicySchema.safeParse(labels?.attribution);
+  return parsed.success ? parsed.data : {};
+}
+
+/** RFC-0231: site-level default for material credits, defaulting to byIntent. */
+export function readCreditsSiteDefault(
+  labels: Record<string, unknown> | undefined,
+): AttributionSiteDefault {
+  return readAttributionPolicy(labels).credits ?? "byIntent";
+}