@agent-native/creative-context 0.8.36 → 0.8.37-nightly-20261009124314

package/src/server/generation-context-a2a.spec.ts

@@ -17,6 +17,7 @@ const mocks = vi.hoisted(() => ({
   getRequestOrgId: vi.fn(),
   getRequestUserEmail: vi.fn(() => "user@example.test"),
   createArtifactCapability: vi.fn(),
+  createSnapshotCapability: vi.fn(),
   isCreativeContextLabAvailable: vi.fn(),
 }));
 
@@ -74,11 +75,14 @@ vi.mock("./context.js", () => ({
 vi.mock("./generation-artifact-access.js", () => ({
   assertGenerationArtifactAccess: vi.fn(),
   createGenerationArtifactAccessCapability: mocks.createArtifactCapability,
+  createGenerationCreativeContextSnapshotCapability:
+    mocks.createSnapshotCapability,
 }));
 
 import {
   getGenerationCreativeContext,
   recordGenerationCreativeContext,
+  recordGenerationCreativeContextFromSnapshot,
   resolveGenerationCreativeContext,
   validateGenerationCreativeContext,
 } from "./generation-context.js";
@@ -99,6 +103,7 @@ describe("generation context isolated A2A routing", () => {
     mocks.createArtifactCapability.mockImplementation(
       async (_identity, _target, operation) => `cap-${operation}`,
     );
+    mocks.createSnapshotCapability.mockResolvedValue("snapshot-cap");
     mocks.isCreativeContextLabAvailable.mockResolvedValue(true);
     mocks.callA2A.mockResolvedValue(emptyRemoteContext);
     mocks.listCreativeContexts.mockResolvedValue({ contexts: [] });
@@ -124,6 +129,7 @@ describe("generation context isolated A2A routing", () => {
       contextMode: "auto",
       contextPackId: null,
       reuseLabels: [],
+      onlyIfMissing: true,
     });
 
     expect(mocks.callA2A).toHaveBeenNthCalledWith(1, "resolve", {
@@ -147,18 +153,80 @@ describe("generation context isolated A2A routing", () => {
       },
       artifactAccessCapability: "cap-read",
     });
-    expect(mocks.callA2A).toHaveBeenNthCalledWith(
-      4,
-      "record",
-      expect.objectContaining({
-        artifactId: "deck-1",
-        artifactAccessCapability: "cap-record",
-      }),
-    );
+    expect(mocks.callA2A).toHaveBeenNthCalledWith(4, "record", {
+      appId: "slides",
+      artifactType: "deck",
+      artifactId: "deck-1",
+      contextMode: "auto",
+      contextPackId: null,
+      reuseLabels: [],
+      onlyIfMissing: true,
+      artifactAccessCapability: "cap-record",
+    });
     expect(mocks.recordLocal).not.toHaveBeenCalled();
     expect(mocks.getLocal).not.toHaveBeenCalled();
   });
 
+  it("routes persisted provenance snapshots without reading mutable settings", async () => {
+    const input = {
+      appId: "content",
+      artifactType: "document",
+      artifactId: "document-1",
+      contextMode: "pinned" as const,
+      contextPackId: "revoked-pack",
+      reuseLabels: [
+        {
+          itemId: "item-1",
+          itemVersionId: "item-version-1",
+          kind: "brand-voice",
+          label: "Brand voice",
+          dataRole: "untrusted-reference" as const,
+        },
+      ],
+      elementProvenance: [
+        {
+          elementId: "document-1",
+          influence: "reference-conditioned" as const,
+          itemId: "item-1",
+          itemVersionId: "item-version-1",
+          label: "Brand voice",
+        },
+      ],
+      onlyIfMissing: true,
+    };
+
+    await recordGenerationCreativeContextFromSnapshot(input);
+
+    expect(mocks.readAppState).not.toHaveBeenCalled();
+    expect(mocks.callA2A).toHaveBeenCalledWith("record", {
+      ...input,
+      snapshotCapability: "snapshot-cap",
+      artifactAccessCapability: "cap-record",
+    });
+    expect(mocks.createSnapshotCapability).toHaveBeenCalledWith(input);
+    expect(mocks.recordLocal).not.toHaveBeenCalled();
+  });
+
+  it("keeps an explicit local read local when saved mode is auto", async () => {
+    const identity = {
+      appId: "content",
+      artifactType: "document",
+      artifactId: "document-1",
+    };
+    const localRecord = { contextMode: "off", contextPackId: null };
+    mocks.getLocal.mockResolvedValue(localRecord);
+
+    await expect(
+      getGenerationCreativeContext(identity, { localOnly: true }),
+    ).resolves.toEqual(localRecord);
+
+    expect(mocks.getLocal).toHaveBeenCalledWith(
+      identity,
+      expect.objectContaining({ db: undefined }),
+    );
+    expect(mocks.callA2A).not.toHaveBeenCalled();
+  });
+
   it.each([
     { path: "isolated A2A", hasA2A: true },
     { path: "local storage", hasA2A: false },

package/src/server/generation-context.ts

@@ -7,6 +7,7 @@ import {
 import {
   getGenerationCreativeContext as getGenerationCreativeContextLocal,
   recordGenerationCreativeContext as recordGenerationCreativeContextLocal,
+  recordGenerationCreativeContextFromSnapshot as recordGenerationCreativeContextFromSnapshotLocal,
 } from "../store/generation.js";
 import {
   createContextPack,
@@ -30,8 +31,10 @@ import { getCreativeContext } from "./context.js";
 import {
   assertGenerationArtifactAccess,
   createGenerationArtifactAccessCapability,
+  createGenerationCreativeContextSnapshotCapability,
   type GenerationArtifactAccessTarget,
   type GenerationArtifactIdentity,
+  type GenerationCreativeContextSnapshot,
 } from "./generation-artifact-access.js";
 import {
   callIsolatedCreativeContextA2A,
@@ -617,6 +620,58 @@ export async function recordGenerationCreativeContext(
   });
 }
 
+export async function recordGenerationCreativeContextFromSnapshot(
+  input: Omit<
+    IsolatedRecordPayload,
+    "artifactAccessCapability" | "snapshotCapability"
+  >,
+  options: { db?: any; artifactAccess?: GenerationArtifactAccessTarget } = {},
+) {
+  if (!input.onlyIfMissing) {
+    throw new Error("Creative Context snapshots must be recorded idempotently");
+  }
+  if (!(await creativeContextLabEnabled())) return null;
+  const artifactAccessTarget = collaborativeArtifactTarget(
+    input,
+    options.artifactAccess,
+  );
+  if (
+    input.contextMode !== "off" &&
+    !options.db &&
+    hasIsolatedCreativeContextA2A()
+  ) {
+    const snapshot = {
+      ...input,
+      onlyIfMissing: true,
+    } satisfies GenerationCreativeContextSnapshot;
+    const snapshotCapability =
+      await createGenerationCreativeContextSnapshotCapability(snapshot);
+    const artifactAccessCapability = artifactAccessTarget
+      ? await createGenerationArtifactAccessCapability(
+          input,
+          artifactAccessTarget,
+          "record",
+        )
+      : undefined;
+    return callIsolatedCreativeContextA2A("record", {
+      ...snapshot,
+      snapshotCapability,
+      artifactAccessCapability,
+    });
+  }
+  const artifactAccess = artifactAccessTarget
+    ? await assertGenerationArtifactAccess(
+        input,
+        artifactAccessTarget,
+        "record",
+      )
+    : undefined;
+  return recordGenerationCreativeContextFromSnapshotLocal(input, {
+    db: options.db,
+    artifactAccess,
+  });
+}
+
 export async function getGenerationCreativeContext(
   input: {
     appId: string;
@@ -626,6 +681,7 @@ export async function getGenerationCreativeContext(
   options: {
     artifactAccess?: GenerationArtifactAccessTarget;
     db?: any;
+    localOnly?: boolean;
   } = {},
 ) {
   if (!(await creativeContextLabEnabled())) return null;
@@ -633,7 +689,7 @@ export async function getGenerationCreativeContext(
     input,
     options.artifactAccess,
   );
-  if (!options.db && hasIsolatedCreativeContextA2A()) {
+  if (!options.db && !options.localOnly && hasIsolatedCreativeContextA2A()) {
     const state = (await readAppState("creative-context")) as {
       contextMode?: "auto" | "off";
     } | null;
@@ -656,5 +712,6 @@ export async function getGenerationCreativeContext(
     : undefined;
   return getGenerationCreativeContextLocal(input, {
     artifactAccess,
+    db: options.db,
   });
 }

package/src/server/isolated-a2a.spec.ts

@@ -174,6 +174,29 @@ describe("isolated Creative Context A2A", () => {
     expect(() => decodeCreativeContextA2ARequest(requestToken)).toThrow();
   });
 
+  it("rejects the unsigned persisted-snapshot bypass flag", () => {
+    const requestToken = Buffer.from(
+      JSON.stringify({
+        protocol: "creative-context-a2a-v1",
+        requestId: "87f466ae-32f4-4d0f-9de7-96f955e69f7b",
+        operation: "record",
+        payload: {
+          appId: "slides",
+          artifactType: "deck",
+          artifactId: "guessed-deck",
+          contextMode: "pinned",
+          contextPackId: "private-pack",
+          reuseLabels: [],
+          onlyIfMissing: true,
+          persistedSnapshot: true,
+        },
+      }),
+      "utf8",
+    ).toString("base64url");
+
+    expect(() => decodeCreativeContextA2ARequest(requestToken)).toThrow();
+  });
+
   it("fails closed when the isolated URL has no signing secret", async () => {
     delete process.env.CREATIVE_CONTEXT_A2A_KEY;
     delete process.env.A2A_SECRET;

package/src/server/isolated-a2a.ts

@@ -56,6 +56,8 @@ const generationRecordInputSchema = generationIdentitySchema
     contextPackId: boundedId.nullable(),
     reuseLabels: z.array(reuseLabelSchema).max(100),
     elementProvenance: z.array(elementProvenanceSchema).max(500).optional(),
+    onlyIfMissing: z.boolean().optional(),
+    snapshotCapability: z.string().min(1).max(8_192).optional(),
   })
   .strict();
 const artifactAccessCapabilitySchema = z.string().min(1).max(8_192);
@@ -412,5 +414,7 @@ export type IsolatedRecordPayload = {
   contextPackId: string | null;
   reuseLabels: CreativeContextReuseLabel[];
   elementProvenance?: CreativeContextElementProvenance[];
+  onlyIfMissing?: boolean;
+  snapshotCapability?: string;
   artifactAccessCapability?: string;
 };

package/src/store/access.integration.spec.ts

@@ -607,6 +607,151 @@ describe("creative context access and revocation", () => {
     ).rejects.toThrow(/verified by the host application/i);
   });
 
+  it("records one generation context for concurrent create retries", async () => {
+    const { exec, runWithRequestContext, store } = await setup();
+    const input = {
+      appId: "content",
+      artifactType: "document",
+      artifactId: "concurrent-create-retry",
+      contextMode: "off" as const,
+      contextPackId: null,
+      reuseLabels: [],
+      elementProvenance: [
+        {
+          elementId: "concurrent-create-retry",
+          influence: "generated" as const,
+        },
+      ],
+      onlyIfMissing: true,
+    };
+    const record = () =>
+      runWithRequestContext({ userEmail: "alice@example.test" }, () =>
+        store.recordGenerationCreativeContext(input),
+      );
+
+    const records = await Promise.all([record(), record(), record()]);
+    expect(new Set(records.map((entry) => entry.id)).size).toBe(1);
+    const stored = await exec.execute({
+      sql: `SELECT id FROM creative_context_generation_records
+        WHERE app_id = ? AND artifact_type = ? AND artifact_id = ?
+          AND owner_email = ? AND org_id IS NULL`,
+      args: ["content", "document", input.artifactId, "alice@example.test"],
+    });
+    expect(stored.rows).toHaveLength(1);
+    expect(stored.rows[0]?.id).toBe(records[0]?.id);
+  });
+
+  it("records a validated provenance snapshot after its context pack is revoked", async () => {
+    const { runWithRequestContext, store } = await setup();
+    const input = {
+      appId: "content",
+      artifactType: "document",
+      artifactId: "snapshot-after-pack-revocation",
+      contextMode: "pinned" as const,
+      contextPackId: "pack-that-is-no-longer-accessible",
+      reuseLabels: [
+        {
+          itemId: "historical-item",
+          itemVersionId: "historical-item-version",
+          kind: "brand-voice",
+          label: "Saved voice",
+          dataRole: "untrusted-reference" as const,
+          influence: "reference-conditioned" as const,
+        },
+      ],
+      elementProvenance: [
+        {
+          elementId: "snapshot-after-pack-revocation",
+          influence: "reference-conditioned" as const,
+          itemId: "historical-item",
+          itemVersionId: "historical-item-version",
+          label: "Saved voice",
+        },
+      ],
+      onlyIfMissing: true,
+    };
+
+    await expect(
+      runWithRequestContext({ userEmail: "alice@example.test" }, () =>
+        store.recordGenerationCreativeContextFromSnapshot(input),
+      ),
+    ).resolves.toMatchObject({
+      artifactId: input.artifactId,
+      contextMode: "pinned",
+      contextPackId: input.contextPackId,
+      elementProvenance: input.elementProvenance,
+    });
+  });
+
+  it("repairs a missing generation projection when onlyIfMissing is retried", async () => {
+    const { runWithRequestContext, store } = await setup();
+    const server = await import("../server/index.js");
+    const projectionRecord = vi
+      .fn()
+      .mockRejectedValueOnce(new Error("projection unavailable"))
+      .mockResolvedValue(undefined);
+    server.configureCreativeContext({
+      projections: { generation: { record: projectionRecord } },
+    });
+
+    const input = {
+      appId: "content",
+      artifactType: "document",
+      artifactId: "projection-retry",
+      contextMode: "off" as const,
+      contextPackId: null,
+      reuseLabels: [],
+      elementProvenance: [
+        { elementId: "original-element", influence: "generated" as const },
+      ],
+      onlyIfMissing: true,
+    };
+    const record = (request: typeof input) =>
+      runWithRequestContext({ userEmail: "alice@example.test" }, () =>
+        store.recordGenerationCreativeContext(request),
+      );
+
+    await expect(record(input)).rejects.toThrow("projection unavailable");
+    expect(projectionRecord).toHaveBeenCalledTimes(1);
+
+    const persisted = await runWithRequestContext(
+      { userEmail: "alice@example.test" },
+      () =>
+        store.getGenerationCreativeContext({
+          appId: input.appId,
+          artifactType: input.artifactType,
+          artifactId: input.artifactId,
+        }),
+    );
+    expect(persisted).toMatchObject({
+      elementProvenance: input.elementProvenance,
+    });
+
+    const retry = {
+      ...input,
+      elementProvenance: [
+        { elementId: "retry-element", influence: "generated" as const },
+      ],
+    };
+    const retried = await record(retry);
+
+    expect(retried).toMatchObject({
+      id: persisted?.id,
+      elementProvenance: input.elementProvenance,
+    });
+    expect(projectionRecord).toHaveBeenCalledTimes(2);
+    expect(projectionRecord).toHaveBeenNthCalledWith(
+      2,
+      expect.objectContaining({
+        appId: input.appId,
+        artifactType: input.artifactType,
+        artifactId: input.artifactId,
+        contextPackId: null,
+        elementProvenance: input.elementProvenance,
+      }),
+    );
+  });
+
   it("appends media enrichment while preserving version-pinned pack evidence", async () => {
     const { exec, runWithRequestContext, store } = await setup();
     await exec.execute({

package/src/store/generation.ts

@@ -1,5 +1,5 @@
 import { assertAccess } from "@agent-native/core/sharing";
-import { and, desc, eq } from "drizzle-orm";
+import { and, desc, eq, isNull, sql } from "drizzle-orm";
 
 import { getCreativeContext } from "../server/context.js";
 import {
@@ -78,11 +78,54 @@ export async function recordGenerationCreativeContext(
     contextPackId: string | null;
     reuseLabels: CreativeContextReuseLabel[];
     elementProvenance?: CreativeContextElementProvenance[];
+    onlyIfMissing?: boolean;
   },
   options: {
     db?: any;
     artifactAccess?: GenerationArtifactAccessProof;
   } = {},
+): Promise<CreativeContextGenerationRecord> {
+  return recordGenerationCreativeContextInternal(input, options, false);
+}
+
+export async function recordGenerationCreativeContextFromSnapshot(
+  input: {
+    appId: string;
+    artifactType: string;
+    artifactId: string;
+    contextMode: "off" | "auto" | "pinned";
+    contextPackId: string | null;
+    reuseLabels: CreativeContextReuseLabel[];
+    elementProvenance?: CreativeContextElementProvenance[];
+    onlyIfMissing?: boolean;
+  },
+  options: {
+    db?: any;
+    artifactAccess?: GenerationArtifactAccessProof;
+  } = {},
+): Promise<CreativeContextGenerationRecord> {
+  if (!input.onlyIfMissing) {
+    throw new Error("Creative Context snapshots must be recorded idempotently");
+  }
+  return recordGenerationCreativeContextInternal(input, options, true);
+}
+
+async function recordGenerationCreativeContextInternal(
+  input: {
+    appId: string;
+    artifactType: string;
+    artifactId: string;
+    contextMode: "off" | "auto" | "pinned";
+    contextPackId: string | null;
+    reuseLabels: CreativeContextReuseLabel[];
+    elementProvenance?: CreativeContextElementProvenance[];
+    onlyIfMissing?: boolean;
+  },
+  options: {
+    db?: any;
+    artifactAccess?: GenerationArtifactAccessProof;
+  },
+  fromValidatedSnapshot: boolean,
 ): Promise<CreativeContextGenerationRecord> {
   const elementProvenance =
     input.elementProvenance ??
@@ -99,7 +142,7 @@ export async function recordGenerationCreativeContext(
     reuseLabels: input.reuseLabels,
     elementProvenance,
   });
-  if (input.contextPackId) {
+  if (input.contextPackId && !fromValidatedSnapshot) {
     await assertAccess(
       "creative-context-pack",
       input.contextPackId,
@@ -108,7 +151,7 @@ export async function recordGenerationCreativeContext(
       { skipResourceBody: true },
     );
   }
-  if (input.contextPackId) {
+  if (input.contextPackId && !fromValidatedSnapshot) {
     const { getDb, schema } = getCreativeContext();
     const db = options.db ?? getDb();
     const members = await db
@@ -156,18 +199,64 @@ export async function recordGenerationCreativeContext(
     ownerEmail: actor.ownerEmail,
     orgId: options.artifactAccess ? actor.orgId : null,
   };
-  await db.insert(schema.generationRecords).values(row);
-  await getCreativeContext().projections?.generation?.record({
-    appId: input.appId,
-    artifactType: input.artifactType,
-    artifactId: input.artifactId,
-    contextPackId: input.contextPackId,
-    elementProvenance,
-  });
-  return {
-    ...row,
-    elementProvenance: parseJson(row.elementProvenance, []),
+  let recorded: {
+    record: CreativeContextGenerationRecord;
+    inserted: boolean;
   };
+  if (input.onlyIfMissing) {
+    // Matching retries can reach separate server processes, so coordinate in Postgres.
+    const scopeKey = options.artifactAccess
+      ? ["org", actor.orgId, input.appId, input.artifactType, input.artifactId]
+      : [
+          "owner",
+          actor.ownerEmail,
+          input.appId,
+          input.artifactType,
+          input.artifactId,
+        ];
+    recorded = await db.transaction(async (tx: any) => {
+      await tx.execute(
+        sql`SELECT pg_advisory_xact_lock(hashtextextended(${`creative-context-generation:${JSON.stringify(scopeKey)}`}, 0::bigint))`,
+      );
+      const existing = await getGenerationCreativeContext(
+        {
+          appId: input.appId,
+          artifactType: input.artifactType,
+          artifactId: input.artifactId,
+        },
+        { artifactAccess: options.artifactAccess, db: tx },
+      );
+      if (existing) return { record: existing, inserted: false };
+
+      await tx.insert(schema.generationRecords).values(row);
+      return {
+        record: {
+          ...row,
+          elementProvenance: parseJson(row.elementProvenance, []),
+        },
+        inserted: true,
+      };
+    });
+  } else {
+    await db.insert(schema.generationRecords).values(row);
+    recorded = {
+      record: {
+        ...row,
+        elementProvenance: parseJson(row.elementProvenance, []),
+      },
+      inserted: true,
+    };
+  }
+  if (recorded.inserted || input.onlyIfMissing) {
+    await getCreativeContext().projections?.generation?.record({
+      appId: recorded.record.appId,
+      artifactType: recorded.record.artifactType,
+      artifactId: recorded.record.artifactId,
+      contextPackId: recorded.record.contextPackId,
+      elementProvenance: recorded.record.elementProvenance,
+    });
+  }
+  return recorded.record;
 }
 
 export async function getGenerationCreativeContext(
@@ -178,6 +267,7 @@ export async function getGenerationCreativeContext(
   },
   options: {
     artifactAccess?: GenerationArtifactAccessProof;
+    db?: any;
   } = {},
 ): Promise<CreativeContextGenerationRecord | null> {
   const { getDb, schema } = getCreativeContext();
@@ -192,8 +282,11 @@ export async function getGenerationCreativeContext(
   }
   const actorScope = options.artifactAccess
     ? eq(schema.generationRecords.orgId, actor.orgId!)
-    : eq(schema.generationRecords.ownerEmail, actor.ownerEmail);
-  const rows = await getDb()
+    : and(
+        eq(schema.generationRecords.ownerEmail, actor.ownerEmail),
+        isNull(schema.generationRecords.orgId),
+      );
+  const rows = await (options.db ?? getDb())
     .select()
     .from(schema.generationRecords)
     .where(