@warpgogol/werkstatt-shared 0.15.0 → 0.16.0

package/src/agent/search.ts

@@ -20,6 +20,7 @@ Mechanical v1 to v2 header migration across the workspace: 942 files rewritten
   <item>RFC-1097: sweep — werkstatt-engine clean
 
 Sweep batch 4: 73 Compass headers on headerless engine files (certification, component-runtime, isolation, evolution, testing), real KEY_DECISIONS on 75 files (kernel, cache, dht, swim, gitmesh, runtime), ~80 purpose expansions (CONTRACT-02/PURPOSE-02), non-goals on 13 CONTRACT-03 files, CS-07 history literal fix repo-wide (253 files). Policy: .template.ts/.template.astro excludedPaths. werkstatt-engine now 0 diagnostics.</item>
+  <item>RFC-1115: SearchChunk gains citation fields (title, canonicalUrl, updatedAt); SearchResult flattened to { title, canonicalUrl, updatedAt, lang, type, score, text }; SEARCH_MANIFEST_SCHEMA_VERSION "1" → "2".</item>
 </CHANGE_SUMMARY>
 */
 
@@ -44,8 +45,8 @@ export const SEARCH_DEFAULT_TOP_K = 5;
 /** Maximum character length for a chunk's `text` field (truncated before embedding). */
 export const SEARCH_CHUNK_TEXT_MAX_LENGTH = 2000;
 
-/** Schema version for the search manifest. */
-export const SEARCH_MANIFEST_SCHEMA_VERSION = "1";
+/** Schema version for the search manifest. RFC-1115: "2" adds citation fields to chunks. */
+export const SEARCH_MANIFEST_SCHEMA_VERSION = "2";
 
 /** Static asset path for the generated search manifest. */
 export const SEARCH_MANIFEST_PATH = "public/api/agent/v1/search-manifest.json";
@@ -86,6 +87,12 @@ export interface SearchChunk {
   heading: string | null;
   /** Body text extracted from the block, truncated to SEARCH_CHUNK_TEXT_MAX_LENGTH. */
   text: string;
+  /** RFC-1115: display title for citations (from heading; null when absent). */
+  title: string | null;
+  /** RFC-1115: absolute canonical URL (site origin + url) — citable without a follow-up fetch. */
+  canonicalUrl: string;
+  /** RFC-1115: source-backed update stamp YYYY-MM-DD (RFC-0317); null when unknown. */
+  updatedAt: string | null;
 }
 
 /** Static search manifest — build-time output written to public/api/agent/v1/search-manifest.json. */
@@ -117,11 +124,25 @@ export interface SearchQuery {
   topK?: number;
 }
 
-/** A single search result — chunk + similarity score. */
+/**
+ * RFC-1115: a single search result — flattened citation shape.
+ * Carries everything an agent needs to cite without a follow-up fetch.
+ */
 export interface SearchResult {
-  chunk: SearchChunk;
+  /** Display title (from chunk heading; null when absent). */
+  title: string | null;
+  /** Absolute canonical URL of the chunk's page or resource. */
+  canonicalUrl: string;
+  /** Source-backed update stamp YYYY-MM-DD (RFC-0317); null when unknown. */
+  updatedAt: string | null;
+  /** ISO 639-1 language code. */
+  lang: string;
+  /** Content type of the underlying chunk. */
+  type: SearchChunkType;
   /** Cosine similarity score (0..1, higher = more similar). */
   score: number;
+  /** Body text of the chunk. */
+  text: string;
 }
 
 /** Response from the search endpoint. */

package/src/agent/tests/api-catalog.test.ts

@@ -8,6 +8,7 @@
 </MODULE_MAP>
 <CHANGE_SUMMARY>
   <item>RFC-0783: initial API Catalog projection tests.</item>
+  <item>RFC-1113: align agent discovery surface with RFC 9727 and MCP 2026-07-28 stateless era</item>
 </CHANGE_SUMMARY>
 */
 
@@ -17,6 +18,7 @@ import { buildAgentSurfaceManifest } from "../manifest.ts";
 
 test("buildApiCatalog: empty manifest yields service-meta + service-doc links", () => {
   const manifest = buildAgentSurfaceManifest({
+    generatedAt: "2026-01-01T00:00:00.000Z",
     site: "s",
     baseUrl: "https://s.example",
     languages: { default: "de", supported: ["de"] },
@@ -34,6 +36,7 @@ test("buildApiCatalog: empty manifest yields service-meta + service-doc links",
 
 test("buildApiCatalog: one knowledge ref → one item link", () => {
   const manifest = buildAgentSurfaceManifest({
+    generatedAt: "2026-01-01T00:00:00.000Z",
     site: "s",
     baseUrl: "https://s.example",
     languages: { default: "de", supported: ["de"] },
@@ -51,6 +54,7 @@ test("buildApiCatalog: one knowledge ref → one item link", () => {
 
 test("buildApiCatalog: mcp interface adds service-desc + service links", () => {
   const manifest = buildAgentSurfaceManifest({
+    generatedAt: "2026-01-01T00:00:00.000Z",
     site: "s",
     baseUrl: "https://s.example",
     languages: { default: "de", supported: ["de"] },
@@ -69,6 +73,7 @@ test("buildApiCatalog: determinism — same input produces identical output", ()
     site: "s",
     baseUrl: "https://s.example",
     languages: { default: "de", supported: ["de"] },
+    generatedAt: "2026-01-01T00:00:00.000Z",
     knowledge: [
       { domain: "offer", url: "/api/agent/v1/offer.json", schema: "gogol.agent.knowledge/offer@1" },
       { domain: "team", url: "/api/agent/v1/team.json", schema: "gogol.agent.knowledge/team@1" },
@@ -82,6 +87,7 @@ test("buildApiCatalog: determinism — same input produces identical output", ()
 
 test("buildApiCatalog: links are sorted by href within each relation", () => {
   const manifest = buildAgentSurfaceManifest({
+    generatedAt: "2026-01-01T00:00:00.000Z",
     site: "s",
     baseUrl: "https://s.example",
     languages: { default: "de", supported: ["de"] },

package/src/agent/tests/ard-catalog.test.ts

@@ -5,6 +5,7 @@
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>Initial ARD ai-catalog.json projection tests.</item>
+  <item>RFC-1113: align agent discovery surface with RFC 9727 and MCP 2026-07-28 stateless era</item>
 </CHANGE_SUMMARY>
 */
 
@@ -14,6 +15,7 @@ import { buildAgentSurfaceManifest } from "../manifest.ts";
 
 test("buildArdCatalog: produces specVersion, host, and entries array", () => {
   const manifest = buildAgentSurfaceManifest({
+    generatedAt: "2026-01-01T00:00:00.000Z",
     site: "s",
     baseUrl: "https://s.example",
     languages: { default: "de", supported: ["de"] },
@@ -27,6 +29,7 @@ test("buildArdCatalog: produces specVersion, host, and entries array", () => {
 
 test("buildArdCatalog: each entry has identifier, displayName, type, url, representativeQueries", () => {
   const manifest = buildAgentSurfaceManifest({
+    generatedAt: "2026-01-01T00:00:00.000Z",
     site: "s",
     baseUrl: "https://s.example",
     languages: { default: "de", supported: ["de"] },
@@ -48,6 +51,7 @@ test("buildArdCatalog: each entry has identifier, displayName, type, url, repres
 
 test("buildArdCatalog: MCP interface adds MCP server entry", () => {
   const manifest = buildAgentSurfaceManifest({
+    generatedAt: "2026-01-01T00:00:00.000Z",
     site: "s",
     baseUrl: "https://s.example",
     languages: { default: "de", supported: ["de"] },
@@ -62,6 +66,7 @@ test("buildArdCatalog: MCP interface adds MCP server entry", () => {
 
 test("buildArdCatalog: knowledge refs produce entries", () => {
   const manifest = buildAgentSurfaceManifest({
+    generatedAt: "2026-01-01T00:00:00.000Z",
     site: "s",
     baseUrl: "https://s.example",
     languages: { default: "de", supported: ["de"] },
@@ -78,6 +83,7 @@ test("buildArdCatalog: knowledge refs produce entries", () => {
 
 test("buildArdCatalog: entries are sorted by identifier", () => {
   const manifest = buildAgentSurfaceManifest({
+    generatedAt: "2026-01-01T00:00:00.000Z",
     site: "s",
     baseUrl: "https://s.example",
     languages: { default: "de", supported: ["de"] },
@@ -97,6 +103,7 @@ test("buildArdCatalog: determinism — same input produces identical output", ()
     site: "s",
     baseUrl: "https://s.example",
     languages: { default: "de", supported: ["de"] },
+    generatedAt: "2026-01-01T00:00:00.000Z",
     knowledge: [
       { domain: "offer", url: "/api/agent/v1/offer.json", schema: "gogol.agent.knowledge/offer@1" },
     ],
@@ -109,6 +116,7 @@ test("buildArdCatalog: determinism — same input produces identical output", ()
 
 test("buildArdCatalog: host identifier uses did:web format with domain", () => {
   const manifest = buildAgentSurfaceManifest({
+    generatedAt: "2026-01-01T00:00:00.000Z",
     site: "warpgogol-com",
     baseUrl: "https://warpgogol.com",
     languages: { default: "de", supported: ["de"] },
@@ -120,6 +128,7 @@ test("buildArdCatalog: host identifier uses did:web format with domain", () => {
 
 test("buildArdCatalog: default hostDisplayName falls back to site name", () => {
   const manifest = buildAgentSurfaceManifest({
+    generatedAt: "2026-01-01T00:00:00.000Z",
     site: "my-site",
     baseUrl: "https://example.com",
     languages: { default: "de", supported: ["de"] },

package/src/agent/tests/manifest.test.ts

@@ -9,11 +9,15 @@
 <CHANGE_SUMMARY>
   <item>RFC-0286: initial builder tests.</item>
   <item>RFC-0954: add search interface tests.</item>
+  <item>RFC-1113: align agent discovery surface with RFC 9727 and MCP 2026-07-28 stateless era</item>
+  <item>RFC-1114: add a2a interface + supportedProtocols tests (AC-5).</item>
+  <item>RFC-1114: minimal real A2A endpoint + honest agent card</item>
 </CHANGE_SUMMARY>
 */
 
 import { test, expect } from "vitest";
 import {
+  AGENT_SURFACE_SCHEMA_ID,
   AGENT_SURFACE_VERSION,
   buildAgentSurfaceManifest,
   computeAgentManifestContentHash,
@@ -25,6 +29,7 @@ const baseInput = {
   site: "warpgogol-com",
   baseUrl: "https://warpgogol.com/",
   languages: { default: "de", supported: ["uk", "de"] },
+  generatedAt: "2026-01-01T00:00:00.000Z",
 };
 
 test("buildAgentSurfaceManifest: strips trailing slash and sorts supported languages", () => {
@@ -39,6 +44,7 @@ test("buildAgentSurfaceManifest: safe default — empty knowledge/actions, null
   expect(m.actions).toEqual([]);
   expect(m.interfaces.openapi).toBe(null);
   expect(m.interfaces.mcp).toBe(null);
+  expect(m.interfaces.a2a).toBe(null);
   expect(m.interfaces.twins).toBe(null);
   expect(m.interfaces.search).toBe(null);
   expect(m.proof).toBe(null);
@@ -149,3 +155,68 @@ test("computeSignedContentHash: matches computeAgentManifestContentHash for same
   const doc = { a: 1, b: 2, contentHash: "x", proof: null };
   expect(computeSignedContentHash(doc)).toBe(computeAgentManifestContentHash(doc));
 });
+
+// ---------------------------------------------------------------------------
+// RFC-1113: discovery metadata fields
+// ---------------------------------------------------------------------------
+
+test("buildAgentSurfaceManifest: emits $schema, generatedAt, supportedProtocols", () => {
+  const m = buildAgentSurfaceManifest(baseInput);
+  expect(m.$schema).toBe(AGENT_SURFACE_SCHEMA_ID);
+  expect(m.generatedAt).toBe("2026-01-01T00:00:00.000Z");
+  // Unconditional discovery artifacts only — no interfaces were provided.
+  expect(m.supportedProtocols).toEqual(["agent-skills", "ard", "dns-aid", "linkset", "llms"]);
+});
+
+test("buildAgentSurfaceManifest: supportedProtocols follows emitted interfaces", () => {
+  const m = buildAgentSurfaceManifest({
+    ...baseInput,
+    hasTwins: true,
+    openapiUrl: "/.well-known/agent.openapi.json",
+    mcp: { url: "/api/agent/mcp", protocolVersion: "2026-07-28" },
+    search: { url: "/api/agent/search", model: "@cf/baai/bge-m3", dimensions: 1024 },
+  });
+  expect(m.supportedProtocols).toEqual([
+    "agent-skills",
+    "ard",
+    "dns-aid",
+    "linkset",
+    "llms",
+    "mcp",
+    "openapi",
+    "search",
+    "twins",
+  ]);
+});
+
+// ---------------------------------------------------------------------------
+// RFC-1114: a2a interface (AC-5)
+// ---------------------------------------------------------------------------
+
+test("buildAgentSurfaceManifest: populates interfaces.a2a and lists a2a in supportedProtocols", () => {
+  const m = buildAgentSurfaceManifest({
+    ...baseInput,
+    a2a: { url: "/api/agent/a2a", protocolVersion: "1.0" },
+  });
+  expect(m.interfaces.a2a).toEqual({ url: "/api/agent/a2a", protocolVersion: "1.0" });
+  expect(m.supportedProtocols).toContain("a2a");
+});
+
+test("buildAgentSurfaceManifest: a2a absent from supportedProtocols when no a2a interface", () => {
+  const m = buildAgentSurfaceManifest(baseInput);
+  expect(m.interfaces.a2a).toBe(null);
+  expect(m.supportedProtocols).not.toContain("a2a");
+});
+
+test("buildAgentSurfaceManifest: generatedAt does not change contentHash (AC-3)", () => {
+  const a = buildAgentSurfaceManifest(baseInput);
+  const b = buildAgentSurfaceManifest({ ...baseInput, generatedAt: "2026-12-31T23:59:59.000Z" });
+  expect(a.contentHash).toBe(b.contentHash);
+  expect(a.generatedAt).not.toBe(b.generatedAt);
+});
+
+test("computeAgentManifestContentHash: excludes generatedAt", () => {
+  const doc = { a: 1, generatedAt: "2026-01-01T00:00:00Z" };
+  const other = { a: 1, generatedAt: "2026-06-06T06:06:06Z" };
+  expect(computeAgentManifestContentHash(doc)).toBe(computeAgentManifestContentHash(other));
+});

package/src/agent/tests/mcp-card.test.ts

@@ -8,6 +8,7 @@
 </MODULE_MAP>
 <CHANGE_SUMMARY>
   <item>RFC-0783: initial MCP Server Card projection tests.</item>
+  <item>RFC-1113: align agent discovery surface with RFC 9727 and MCP 2026-07-28 stateless era</item>
 </CHANGE_SUMMARY>
 */
 
@@ -17,6 +18,7 @@ import { buildAgentSurfaceManifest } from "../manifest.ts";
 
 test("buildMcpServerCard: null mcp → returns null", () => {
   const manifest = buildAgentSurfaceManifest({
+    generatedAt: "2026-01-01T00:00:00.000Z",
     site: "s",
     baseUrl: "https://s.example",
     languages: { default: "de", supported: ["de"] },
@@ -26,6 +28,7 @@ test("buildMcpServerCard: null mcp → returns null", () => {
 
 test("buildMcpServerCard: mcp interface → card with correct fields", () => {
   const manifest = buildAgentSurfaceManifest({
+    generatedAt: "2026-01-01T00:00:00.000Z",
     site: "warpgogol",
     baseUrl: "https://warpgogol.com",
     languages: { default: "de", supported: ["de"] },
@@ -49,6 +52,7 @@ test("buildMcpServerCard: determinism — same input produces identical output",
     site: "s",
     baseUrl: "https://s.example",
     languages: { default: "de", supported: ["de"] },
+    generatedAt: "2026-01-01T00:00:00.000Z",
     mcp: { url: "/api/agent/mcp", protocolVersion: "2025-06-18" },
   };
   const a = buildMcpServerCard(buildAgentSurfaceManifest(input));

package/src/agent/tests/openapi.test.ts

@@ -9,6 +9,7 @@
 <CHANGE_SUMMARY>
   <item>RFC-0289: initial OpenAPI formatter tests.</item>
   <item>RFC-0954: add search path projection tests.</item>
+  <item>RFC-1113: align agent discovery surface with RFC 9727 and MCP 2026-07-28 stateless era</item>
 </CHANGE_SUMMARY>
 */
 
@@ -18,6 +19,7 @@ import { buildAgentSurfaceManifest } from "../manifest.ts";
 
 test("formatAgentOpenApi: empty manifest yields a valid document with no paths", () => {
   const manifest = buildAgentSurfaceManifest({
+    generatedAt: "2026-01-01T00:00:00.000Z",
     site: "s",
     baseUrl: "https://s.example",
     languages: { default: "de", supported: ["de"] },
@@ -33,6 +35,7 @@ test("formatAgentOpenApi: empty manifest yields a valid document with no paths",
 
 test("formatAgentOpenApi: one knowledge ref → one GET path + one component schema", () => {
   const manifest = buildAgentSurfaceManifest({
+    generatedAt: "2026-01-01T00:00:00.000Z",
     site: "s",
     baseUrl: "https://s.example",
     languages: { default: "de", supported: ["de"] },
@@ -61,6 +64,7 @@ test("formatAgentOpenApi: one action ref → one POST path with verbatim input/o
     properties: { accepted: { type: "boolean" as const } },
   };
   const manifest = buildAgentSurfaceManifest({
+    generatedAt: "2026-01-01T00:00:00.000Z",
     site: "s",
     baseUrl: "https://s.example",
     languages: { default: "de", supported: ["de"] },
@@ -84,10 +88,25 @@ test("formatAgentOpenApi: one action ref → one POST path with verbatim input/o
   expect(doc.components.schemas["lead.submit-input"]).toEqual(inputSchema);
   expect(doc.components.schemas["lead.submit-output"]).toEqual(outputSchema);
   expect(op!.requestBody!.content["application/json"].schema).toEqual(inputSchema);
+
+  // RFC-1112: Idempotency-Key header parameter.
+  const idemParam = op!.parameters!.find((p) => p.name === "Idempotency-Key");
+  expect(idemParam).toBeTruthy();
+  expect(idemParam!.in).toBe("header");
+  expect(idemParam!.required).toBe(false);
+
+  // RFC-1112: problem+json error responses + shared problem-details schema.
+  expect(doc.components.schemas["problem-details"]).toBeTruthy();
+  for (const status of ["400", "409", "413", "422", "429", "502"]) {
+    const res = op!.responses[status];
+    expect(res, `missing ${status} response`).toBeTruthy();
+    expect(res!.content?.["application/problem+json"]).toBeTruthy();
+  }
 });
 
 test("formatAgentOpenApi: an action ref without a matching capability schema is skipped defensively", () => {
   const manifest = buildAgentSurfaceManifest({
+    generatedAt: "2026-01-01T00:00:00.000Z",
     site: "s",
     baseUrl: "https://s.example",
     languages: { default: "de", supported: ["de"] },
@@ -107,6 +126,7 @@ test("formatAgentOpenApi: an action ref without a matching capability schema is
 
 test("formatAgentOpenApi: mcp interface present → x-gogol-mcp is set", () => {
   const manifest = buildAgentSurfaceManifest({
+    generatedAt: "2026-01-01T00:00:00.000Z",
     site: "s",
     baseUrl: "https://s.example",
     languages: { default: "de", supported: ["de"] },
@@ -118,6 +138,7 @@ test("formatAgentOpenApi: mcp interface present → x-gogol-mcp is set", () => {
 
 test("formatAgentOpenApi: search interface present → /api/agent/search GET path with dynamic lang enum", () => {
   const manifest = buildAgentSurfaceManifest({
+    generatedAt: "2026-01-01T00:00:00.000Z",
     site: "s",
     baseUrl: "https://s.example",
     languages: { default: "de", supported: ["de", "uk"] },
@@ -136,6 +157,7 @@ test("formatAgentOpenApi: search interface present → /api/agent/search GET pat
 
 test("formatAgentOpenApi: search interface absent → no search path", () => {
   const manifest = buildAgentSurfaceManifest({
+    generatedAt: "2026-01-01T00:00:00.000Z",
     site: "s",
     baseUrl: "https://s.example",
     languages: { default: "de", supported: ["de"] },
@@ -144,3 +166,98 @@ test("formatAgentOpenApi: search interface absent → no search path", () => {
   expect(doc.paths["/api/agent/search"]).toBe(undefined);
   expect(doc.components.schemas["search-response"]).toBe(undefined);
 });
+
+test("formatAgentOpenApi: agentGuidance renders into the operation description (RFC-1115 AC-4)", () => {
+  const manifest = buildAgentSurfaceManifest({
+    generatedAt: "2026-01-01T00:00:00.000Z",
+    site: "s",
+    baseUrl: "https://s.example",
+    languages: { default: "de", supported: ["de"] },
+    actions: [
+      {
+        id: "lead.submit",
+        url: "/api/agent/actions/lead.submit",
+        title: { de: "Anfrage senden" },
+        inputSchemaRef: "#/components/schemas/lead.submit-input",
+        entitlement: "agent.actions",
+      },
+    ],
+  });
+  const doc = formatAgentOpenApi(manifest, [
+    {
+      id: "lead.submit",
+      input: { type: "object" },
+      output: { type: "object" },
+      description: { de: "Reicht eine Kontaktanfrage ein." },
+      agentGuidance: {
+        sideEffect: "write",
+        whenToUse: "ein Besucher das Gewerbe kontaktieren will.",
+        whenNotToUse: "die Antwort bereits auf der Seite steht.",
+        retrySemantics: "mit demselben Idempotency-Key sicher wiederholbar.",
+      },
+    },
+  ]);
+  const op = doc.paths["/api/agent/actions/lead.submit"]?.post;
+  expect(op).toBeTruthy();
+  expect(op!.description).toContain("Reicht eine Kontaktanfrage ein.");
+  expect(op!.description).toContain("Use this when ein Besucher das Gewerbe kontaktieren will.");
+  expect(op!.description).toContain("Do not use this when die Antwort bereits auf der Seite steht.");
+  expect(op!.description).toContain("side effects");
+  expect(op!.description).toContain(
+    "Retry semantics: mit demselben Idempotency-Key sicher wiederholbar.",
+  );
+});
+
+test("formatAgentOpenApi: absent agentGuidance falls back to the base description (RFC-1115 AC-5)", () => {
+  const manifest = buildAgentSurfaceManifest({
+    generatedAt: "2026-01-01T00:00:00.000Z",
+    site: "s",
+    baseUrl: "https://s.example",
+    languages: { default: "de", supported: ["de"] },
+    actions: [
+      {
+        id: "lead.submit",
+        url: "/api/agent/actions/lead.submit",
+        title: { de: "Anfrage senden" },
+        inputSchemaRef: "#/components/schemas/lead.submit-input",
+        entitlement: "agent.actions",
+      },
+    ],
+  });
+  const doc = formatAgentOpenApi(manifest, [
+    {
+      id: "lead.submit",
+      input: { type: "object" },
+      output: { type: "object" },
+      description: { de: "Reicht eine Kontaktanfrage ein." },
+    },
+  ]);
+  const op = doc.paths["/api/agent/actions/lead.submit"]?.post;
+  expect(op!.description).toBe("Reicht eine Kontaktanfrage ein.");
+});
+
+test("formatAgentOpenApi: search-response schema matches the flattened citation shape (RFC-1115 AC-1)", () => {
+  const manifest = buildAgentSurfaceManifest({
+    generatedAt: "2026-01-01T00:00:00.000Z",
+    site: "s",
+    baseUrl: "https://s.example",
+    languages: { default: "de", supported: ["de"] },
+    search: { url: "/api/agent/search", model: "@cf/baai/bge-m3", dimensions: 1024 },
+  });
+  const doc = formatAgentOpenApi(manifest, []);
+  const schema = doc.components.schemas["search-response"] as {
+    properties: { results: { items: { required: string[]; properties: Record<string, unknown> } } };
+  };
+  const item = schema.properties.results.items;
+  expect(item.required).toEqual([
+    "title",
+    "canonicalUrl",
+    "updatedAt",
+    "lang",
+    "type",
+    "score",
+    "text",
+  ]);
+  expect(item.properties.canonicalUrl).toEqual({ type: "string" });
+  expect(item.properties.chunk).toBeUndefined();
+});

package/src/component/index.ts

@@ -1,7 +1,9 @@
 /*
 <MODULE_CONTRACT>
   <purpose>Barrel export for @warpgogol/werkstatt-shared/component sub-path. Re-exports component contract types (ComponentId, CapabilityId, EffectClass, IsolationTier, ComponentDeclaration) sunk from @warpgogol/werkstatt-engine per RFC-1104.</purpose>
-  <non-goals>Does not re-export engine component-runtime modules (identity, schemas, runtime registry).</non-goals>
+  <non-goals>
+    <item>Does not re-export engine component-runtime modules (identity, schemas, runtime registry).</item>
+  </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-1104: initial barrel — component contracts sunk from werkstatt-engine.</item>

package/src/fingerprint/index.ts

@@ -1,7 +1,9 @@
 /*
 <MODULE_CONTRACT>
   <purpose>Barrel export for @warpgogol/werkstatt-shared/fingerprint sub-path. Re-exports canonical JSON and hashing primitives sunk from @warpgogol/werkstatt-engine per RFC-1104.</purpose>
-  <non-goals>Does not re-export engine fingerprint modules that stay in engine (fingerprint.ts, path-matcher.ts, normalizers).</non-goals>
+  <non-goals>
+    <item>Does not re-export engine fingerprint modules that stay in engine (fingerprint.ts, path-matcher.ts, normalizers).</item>
+  </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-1104: initial barrel — canonical-json + primitives sunk from werkstatt-engine.</item>

package/src/integration/idempotency.ts

@@ -0,0 +1,88 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+RFC-1112: durable receipt store for agent-action idempotency, backed by the
+same Upstash Redis EU REST endpoint as the RFC-0181 delivery ledger. Maps an
+Idempotency-Key to { receipt, bodyHash } so a replayed request returns the
+original receipt without re-dispatching, and a key reused with a different
+payload is rejected. Stores identifiers only — never lead payload fields.
+</purpose>
+<non-goals>
+  <item>Do not log or embed secrets — the caller injects RestRedisConfig.</item>
+  <item>Do not implement the port contract here — the engine's IdempotencyPort
+        is structurally identical; this adapter satisfies it.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1112: initial receipt store + Upstash Redis REST adapter.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type { ActionReceipt } from "@warpgogol/werkstatt-shared/agent";
+import type { RestRedisConfig } from "./qstash.ts";
+
+/** Stored record: the original receipt plus the request-body hash it was issued for. */
+export interface ReceiptStoreRecord {
+  receipt: ActionReceipt;
+  /** sha256 of the raw request body (HTTP) or canonicalJsonHashV1 of arguments (MCP). */
+  bodyHash: string;
+}
+
+/**
+ * Receipt store contract (RFC-1112). Structurally identical to the engine's
+ * IdempotencyPort — kept here so the adapter type-checks without importing
+ * engine code (werkstatt-shared is a leaf package).
+ */
+export interface ActionReceiptStore {
+  get(key: string): Promise<ReceiptStoreRecord | null>;
+  put(key: string, bodyHash: string, receipt: ActionReceipt, ttlSeconds: number): Promise<void>;
+}
+
+/**
+ * Adapt an Upstash Redis REST endpoint to the ActionReceiptStore (RFC-1112).
+ * `get` is a plain GET; `put` is `SET key JSON NX EX ttl` — NX keeps the first
+ * stored receipt when two same-key requests race. Throws on transport errors
+ * so the caller can decide fail-open semantics.
+ */
+export function restRedisReceiptStore(
+  config: RestRedisConfig,
+  fetchImpl: typeof fetch = fetch,
+): ActionReceiptStore {
+  const prefix = config.prefix ?? "gogol-agent-idem";
+  const headers = {
+    authorization: `Bearer ${config.token}`,
+    "content-type": "application/json",
+  };
+  return {
+    async get(key: string): Promise<ReceiptStoreRecord | null> {
+      const response = await fetchImpl(config.url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(["GET", `${prefix}:${key}`]),
+      });
+      if (!response.ok) {
+        throw new Error(`redis receipt GET failed: ${response.status}`);
+      }
+      const data = (await response.json()) as { result?: string | null };
+      if (typeof data.result !== "string") return null;
+      return JSON.parse(data.result) as ReceiptStoreRecord;
+    },
+    async put(
+      key: string,
+      bodyHash: string,
+      receipt: ActionReceipt,
+      ttlSeconds: number,
+    ): Promise<void> {
+      const record: ReceiptStoreRecord = { receipt, bodyHash };
+      const command = ["SET", `${prefix}:${key}`, JSON.stringify(record), "NX", "EX", String(ttlSeconds)];
+      const response = await fetchImpl(config.url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(command),
+      });
+      if (!response.ok) {
+        throw new Error(`redis receipt SET failed: ${response.status}`);
+      }
+    },
+  };
+}

package/src/integration/index.ts

@@ -116,6 +116,10 @@ export {
   restRedisLedger,
 } from "./qstash.ts";
 
+// RFC-1112: agent-action receipt store (Upstash Redis EU).
+export type { ReceiptStoreRecord, ActionReceiptStore } from "./idempotency.ts";
+export { restRedisReceiptStore } from "./idempotency.ts";
+
 // Runtime modules — explicit re-exports to keep the public API surface clear.
 export type {
   DeliverResult,