create-windy 0.6.12 → 0.6.15

package/template/apps/server/src/jobs/artifact-publisher.ts

@@ -0,0 +1,101 @@
+import {
+  DurableHandlerError,
+  type DurableHandlerContext,
+  type DurableLeaseIdentity,
+} from "@southwind-ai/jobs";
+import { createHash } from "node:crypto";
+import {
+  DurableArtifactPublicationConflictError,
+  type DurableExecutionRepository,
+  type LeaseResult,
+} from "./execution-repository.js";
+
+export function createDurableArtifactPublisher(input: {
+  readonly repository: DurableExecutionRepository;
+  readonly identity: DurableLeaseIdentity;
+  readonly stageKey: string;
+  readonly now: () => Date;
+  readonly assertLease: (result: LeaseResult) => void;
+}): Required<
+  Pick<DurableHandlerContext, "publishArtifact" | "publishArtifactOnce">
+> {
+  return {
+    publishArtifact: async (artifact) => {
+      const result = await input.repository.publishArtifact(
+        input.identity,
+        {
+          id: Bun.randomUUIDv7(),
+          jobId: input.identity.jobId,
+          stageId: input.identity.stageId,
+          ...artifact,
+          createdAt: input.now().toISOString(),
+        },
+        input.now(),
+      );
+      input.assertLease(result);
+    },
+    publishArtifactOnce: async (publicationKey, artifact) => {
+      validatePublicationKey(publicationKey);
+      let result;
+      try {
+        result = await input.repository.publishArtifactOnce(
+          input.identity,
+          {
+            id: stableArtifactId(input.identity, publicationKey),
+            jobId: input.identity.jobId,
+            stageId: input.identity.stageId,
+            ...artifact,
+          },
+          input.now(),
+        );
+      } catch (error) {
+        if (error instanceof DurableArtifactPublicationConflictError) {
+          throw new DurableHandlerError(
+            "ARTIFACT_PUBLICATION_CONFLICT",
+            error.message,
+            false,
+          );
+        }
+        throw error;
+      }
+      if (!result.ok) {
+        input.assertLease(result);
+        throw new Error("产物发布租约校验未终结");
+      }
+      input.assertLease(result);
+      if (result.cancelRequested) {
+        throw new Error("已取消任务不应返回产物发布事实");
+      }
+      return {
+        schemaVersion: 1,
+        publicationKey,
+        artifactId: result.artifact.id,
+        jobId: input.identity.jobId,
+        stageKey: input.stageKey,
+        kind: result.artifact.kind,
+        artifactRef: result.artifact.artifactRef,
+        sha256: result.artifact.sha256,
+      };
+    },
+  };
+}
+
+function validatePublicationKey(value: string) {
+  if (!value || value !== value.trim() || value.length > 160) {
+    throw new DurableHandlerError(
+      "ARTIFACT_PUBLICATION_KEY_INVALID",
+      "产物 publicationKey 必须为 1 到 160 个非空白字符",
+      false,
+    );
+  }
+}
+
+function stableArtifactId(
+  identity: Pick<DurableLeaseIdentity, "jobId" | "stageId">,
+  publicationKey: string,
+) {
+  const digest = createHash("sha256")
+    .update(JSON.stringify([identity.jobId, identity.stageId, publicationKey]))
+    .digest("hex");
+  return `dap_${digest.slice(0, 60)}`;
+}

package/template/apps/server/src/jobs/drizzle-artifact.ts

@@ -4,13 +4,21 @@ import {
   durableJobs,
 } from "@southwind-ai/database";
 import type { DurableLeaseIdentity } from "@southwind-ai/jobs";
-import { eq } from "drizzle-orm";
+import { and, eq, or } from "drizzle-orm";
 import type { NodePgDatabase } from "drizzle-orm/node-postgres";
 import type {
+  DurableArtifactPublication,
+  DurableArtifactPublicationResult,
   DurableExecutionRepository,
   LeaseResult,
 } from "./execution-repository.js";
+import { DurableArtifactPublicationConflictError } from "./execution-repository.js";
 import { activeLeaseWhere } from "./drizzle-lease.js";
+import {
+  assertArtifactPublicationIdentity,
+  sameArtifactPublication,
+} from "./artifact-publication.js";
+import { mapArtifact } from "./drizzle-mappers.js";
 
 type Artifact = Parameters<DurableExecutionRepository["publishArtifact"]>[1];
 
@@ -53,6 +61,70 @@ export function publishDrizzleArtifact(
   });
 }
 
+export function publishDrizzleArtifactOnce(
+  db: NodePgDatabase,
+  identity: DurableLeaseIdentity,
+  artifact: DurableArtifactPublication,
+  now: Date,
+  leaseFailure: () => Promise<LeaseResult>,
+): Promise<DurableArtifactPublicationResult> {
+  return db.transaction(async (tx) => {
+    const [lease] = await tx
+      .select()
+      .from(durableJobLeases)
+      .where(activeLeaseWhere(identity, now))
+      .for("update")
+      .limit(1);
+    if (!lease) {
+      const failure = await leaseFailure();
+      if (failure.ok) {
+        throw new Error("DURABLE_ARTIFACT_LEASE_FAILURE_INVALID");
+      }
+      return failure;
+    }
+    const [job] = await tx
+      .select({ cancelRequestedAt: durableJobs.cancelRequestedAt })
+      .from(durableJobs)
+      .where(eq(durableJobs.id, identity.jobId))
+      .for("update")
+      .limit(1);
+    if (!job) return { ok: false, reason: "not-found" } as const;
+    assertArtifactPublicationIdentity(identity, artifact);
+    const expiresAt = lease.expiresAt.toISOString();
+    if (job.cancelRequestedAt) {
+      return { ok: true, cancelRequested: true, expiresAt } as const;
+    }
+    const leaseResult = {
+      ok: true,
+      cancelRequested: false,
+      expiresAt,
+    } as const;
+    const candidate = { ...artifact, createdAt: now.toISOString() };
+    const [row] = await tx
+      .select()
+      .from(durableJobArtifacts)
+      .where(
+        or(
+          eq(durableJobArtifacts.id, artifact.id),
+          and(
+            eq(durableJobArtifacts.jobId, artifact.jobId),
+            eq(durableJobArtifacts.kind, artifact.kind),
+          ),
+        ),
+      )
+      .limit(1);
+    if (row) {
+      const existing = mapArtifact(row);
+      if (!sameArtifactPublication(existing, artifact)) {
+        throw new DurableArtifactPublicationConflictError();
+      }
+      return { ...leaseResult, artifact: existing };
+    }
+    await tx.insert(durableJobArtifacts).values(toDatabaseArtifact(candidate));
+    return { ...leaseResult, artifact: candidate };
+  });
+}
+
 function toDatabaseArtifact(artifact: Artifact) {
   return {
     ...artifact,

package/template/apps/server/src/jobs/drizzle-execution-repository.ts

@@ -20,7 +20,10 @@ import type {
 } from "./execution-repository.js";
 import { DrizzleDurableRecoveryRepository } from "./drizzle-recovery-repository.js";
 import { claimDurableJob } from "./drizzle-claim.js";
-import { publishDrizzleArtifact } from "./drizzle-artifact.js";
+import {
+  publishDrizzleArtifact,
+  publishDrizzleArtifactOnce,
+} from "./drizzle-artifact.js";
 import { activeLeaseWhere } from "./drizzle-lease.js";
 
 export class DrizzleDurableExecutionRepository implements DurableExecutionRepository {
@@ -95,6 +98,16 @@ export class DrizzleDurableExecutionRepository implements DurableExecutionReposi
     );
   }
 
+  async publishArtifactOnce(
+    identity: DurableLeaseIdentity,
+    artifact: Parameters<DurableExecutionRepository["publishArtifactOnce"]>[1],
+    now: Date,
+  ) {
+    return publishDrizzleArtifactOnce(this.db, identity, artifact, now, () =>
+      this.leaseFailure(identity, now),
+    );
+  }
+
   async complete(identity: DurableLeaseIdentity, now: Date) {
     return this.db.transaction(async (tx) => {
       const [lease] = await tx

package/template/apps/server/src/jobs/drizzle-execution.integration.test.ts

@@ -14,6 +14,7 @@ import { artifactRef } from "@southwind-ai/storage";
 import { DrizzleDurableExecutionRepository } from "./drizzle-execution-repository.js";
 import { DrizzleDurableJobRepository } from "./drizzle-repository.js";
 import { DurableJobService } from "./service.js";
+import { DurableArtifactPublicationConflictError } from "./execution-repository.js";
 
 const databaseUrl = process.env.JOBS_TEST_DATABASE_URL;
 const describePostgres = databaseUrl ? describe : describe.skip;
@@ -38,6 +39,7 @@ describePostgres("PostgreSQL durable execution", () => {
     await pool.query(`truncate table
       governed_export_requests,
       bulk_data_artifacts, bulk_data_jobs, scheduled_task_runs,
+      client_agent_workflow_artifacts,
       durable_job_recoveries, durable_job_failures, durable_job_artifacts,
       durable_job_progress, durable_job_leases, durable_job_attempts,
       durable_job_stages, durable_jobs`);
@@ -170,6 +172,69 @@ describePostgres("PostgreSQL durable execution", () => {
     expect((await service.get(cancelled.job.id))?.artifacts).toEqual([]);
   });
 
+  test("artifact once 重放首发事实且拒绝覆盖", async () => {
+    const service = jobService(pool);
+    const submitted = await service.submit(jobInput("pg-artifact-once"));
+    const execution = new DrizzleDurableExecutionRepository(drizzle(pool));
+    const claim = await execution.claim(claimInput("artifact-once", base));
+    if (!claim) throw new Error("artifact once worker 未领取任务");
+    const publication = {
+      id: "dap_pg_stable",
+      jobId: claim.jobId,
+      stageId: claim.stageId,
+      kind: "result",
+      artifactRef: artifactRef("blob_0123456789abcdef0123456789abcdef"),
+      filename: "result.json",
+      contentType: "application/json",
+      byteSize: 10,
+      sha256: "a".repeat(64),
+      ownerId: "user_pg",
+      metadata: { second: 2, first: 1 },
+    };
+
+    await expect(
+      execution.publishArtifactOnce(
+        claim,
+        { ...publication, jobId: "job_forged" },
+        base,
+      ),
+    ).rejects.toBeInstanceOf(DurableArtifactPublicationConflictError);
+    await expect(
+      execution.publishArtifactOnce(
+        claim,
+        { ...publication, stageId: "stage_forged" },
+        base,
+      ),
+    ).rejects.toBeInstanceOf(DurableArtifactPublicationConflictError);
+    expect((await service.get(submitted.job.id))?.artifacts).toEqual([]);
+
+    const first = await execution.publishArtifactOnce(claim, publication, base);
+    expect(
+      await execution.publishArtifactOnce(
+        claim,
+        { ...publication, metadata: { first: 1, second: 2 } },
+        new Date(base.getTime() + 1),
+      ),
+    ).toEqual(first);
+    await expect(
+      execution.publishArtifactOnce(
+        claim,
+        { ...publication, byteSize: 11 },
+        new Date(base.getTime() + 2),
+      ),
+    ).rejects.toBeInstanceOf(DurableArtifactPublicationConflictError);
+    await expect(
+      execution.publishArtifactOnce(
+        claim,
+        { ...publication, kind: "other-result" },
+        new Date(base.getTime() + 3),
+      ),
+    ).rejects.toBeInstanceOf(DurableArtifactPublicationConflictError);
+    expect((await service.get(submitted.job.id))?.artifacts).toEqual([
+      expect.objectContaining({ id: "dap_pg_stable", byteSize: 10 }),
+    ]);
+  });
+
   test("timeout、running cancel 与人工恢复保留最终事实", async () => {
     const service = jobService(pool);
     const submitted = await service.submit({

package/template/apps/server/src/jobs/drizzle-repository.integration.test.ts

@@ -27,6 +27,7 @@ describePostgres("PostgreSQL durable job repository", () => {
     await pool.query(`truncate table
       governed_export_requests,
       bulk_data_artifacts, bulk_data_jobs, scheduled_task_runs,
+      client_agent_workflow_artifacts,
       durable_job_recoveries, durable_job_failures, durable_job_artifacts, durable_job_progress,
       durable_job_leases, durable_job_attempts, durable_job_stages, durable_jobs`);
   });

package/template/apps/server/src/jobs/execution-repository.ts

@@ -12,6 +12,29 @@ export type LeaseResult =
   | { ok: true; cancelRequested: boolean; expiresAt: string }
   | { ok: false; reason: LeaseRejection };
 
+export type DurableArtifactPublication = Omit<DurableJobArtifact, "createdAt">;
+
+export type DurableArtifactPublicationResult =
+  | Exclude<LeaseResult, { ok: true }>
+  | {
+      ok: true;
+      cancelRequested: true;
+      expiresAt: string;
+    }
+  | {
+      ok: true;
+      cancelRequested: false;
+      expiresAt: string;
+      artifact: DurableJobArtifact;
+    };
+
+export class DurableArtifactPublicationConflictError extends Error {
+  constructor(message = "同一任务产物发布坐标已绑定不同内容") {
+    super(message);
+    this.name = "DurableArtifactPublicationConflictError";
+  }
+}
+
 export interface ClaimDurableJob {
   queue: string;
   workerId: string;
@@ -75,6 +98,11 @@ export interface DurableExecutionRepository {
     artifact: DurableJobArtifact,
     now: Date,
   ): Promise<LeaseResult>;
+  publishArtifactOnce(
+    identity: DurableLeaseIdentity,
+    artifact: DurableArtifactPublication,
+    now: Date,
+  ): Promise<DurableArtifactPublicationResult>;
   complete(identity: DurableLeaseIdentity, now: Date): Promise<LeaseResult>;
   fail(
     identity: DurableLeaseIdentity,

package/template/apps/server/src/jobs/execution.test.ts

@@ -216,7 +216,9 @@ describe("durable job execution", () => {
         expiredAt,
       ),
     ).toMatchObject({ ok: true });
-    expect((await service.get(submitted.job.id))?.artifacts).toHaveLength(1);
+    expect((await service.get(submitted.job.id))?.artifacts).toEqual([
+      expect.objectContaining({ id: "artifact-replay" }),
+    ]);
 
     const cancelled = await service.submit(jobInput("artifact-cancelled"));
     const cancelledClaim = await repository.claim(

package/template/apps/server/src/jobs/in-memory-execution.ts

@@ -17,6 +17,7 @@ import { leaseIdentity, startInMemoryAttempt } from "./in-memory-claim.js";
 import {
   inMemoryLeaseSuccess,
   publishInMemoryArtifact,
+  publishInMemoryArtifactOnce,
   validateInMemoryLease,
 } from "./in-memory-lease.js";
 import {
@@ -121,6 +122,21 @@ export class InMemoryDurableExecutionRepository
     );
   }
 
+  async publishArtifactOnce(
+    identity: DurableLeaseIdentity,
+    artifact: Parameters<DurableExecutionRepository["publishArtifactOnce"]>[1],
+    now: Date,
+  ) {
+    return publishInMemoryArtifactOnce(
+      this.leases,
+      this.artifacts,
+      this.jobs,
+      identity,
+      artifact,
+      now,
+    );
+  }
+
   async complete(identity: DurableLeaseIdentity, now: Date) {
     const validated = validateInMemoryLease(this.leases, identity, now);
     if (!validated.ok) return validated;

package/template/apps/server/src/jobs/in-memory-lease.ts

@@ -4,7 +4,16 @@ import type {
   DurableLeaseIdentity,
 } from "@southwind-ai/jobs";
 import type { LeaseResult } from "./execution-repository.js";
+import type {
+  DurableArtifactPublication,
+  DurableArtifactPublicationResult,
+} from "./execution-repository.js";
+import { DurableArtifactPublicationConflictError } from "./execution-repository.js";
 import { hashLeaseToken } from "./in-memory-claim.js";
+import {
+  assertArtifactPublicationIdentity,
+  sameArtifactPublication,
+} from "./artifact-publication.js";
 
 export function validateInMemoryLease(
   leases: Map<string, DurableJobLease>,
@@ -34,7 +43,7 @@ export function inMemoryLeaseSuccess(
   jobs: Map<string, { cancelRequestedAt?: string }>,
   jobId: string,
   expiresAt: string,
-): LeaseResult {
+): Extract<LeaseResult, { ok: true }> {
   return {
     ok: true,
     cancelRequested: Boolean(jobs.get(jobId)?.cancelRequestedAt),
@@ -64,3 +73,38 @@ export function publishInMemoryArtifact(
   );
   return result;
 }
+
+export function publishInMemoryArtifactOnce(
+  leases: Map<string, DurableJobLease>,
+  artifacts: Map<string, DurableJobArtifact>,
+  jobs: Map<string, { cancelRequestedAt?: string }>,
+  identity: DurableLeaseIdentity,
+  artifact: DurableArtifactPublication,
+  now: Date,
+): DurableArtifactPublicationResult {
+  const validated = validateInMemoryLease(leases, identity, now);
+  if (!validated.ok) return validated;
+  assertArtifactPublicationIdentity(identity, artifact);
+  const lease = inMemoryLeaseSuccess(
+    jobs,
+    identity.jobId,
+    validated.lease.expiresAt,
+  );
+  if (lease.cancelRequested) {
+    return { ...lease, cancelRequested: true };
+  }
+  const publicationLease = { ...lease, cancelRequested: false } as const;
+  const candidate = { ...artifact, createdAt: now.toISOString() };
+  const coordinate = `${artifact.jobId}:${artifact.kind}`;
+  const existing =
+    artifacts.get(coordinate) ||
+    [...artifacts.values()].find(({ id }) => id === artifact.id);
+  if (existing) {
+    if (!sameArtifactPublication(existing, artifact)) {
+      throw new DurableArtifactPublicationConflictError();
+    }
+    return { ...publicationLease, artifact: structuredClone(existing) };
+  }
+  artifacts.set(coordinate, structuredClone(candidate));
+  return { ...publicationLease, artifact: candidate };
+}

package/template/apps/server/src/jobs/legacy-adapter.integration.test.ts

@@ -34,9 +34,11 @@ describePostgres("PostgreSQL legacy durable adapter", () => {
     });
     await pool.query(`
       truncate table
+        governed_export_requests,
         bulk_data_artifacts,
         bulk_data_jobs,
         scheduled_task_runs,
+        client_agent_workflow_artifacts,
         durable_job_recoveries,
         durable_job_failures,
         durable_job_artifacts,

package/template/apps/server/src/jobs/postgres-cleanup-contract.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, test } from "bun:test";
+
+const integrationFiles = new Bun.Glob("**/*.integration.test.ts");
+const migrationFiles = new Bun.Glob("*.sql");
+
+describe("PostgreSQL durable job test cleanup", () => {
+  test("所有显式 durable_jobs TRUNCATE 同批清理受限子表且不使用 CASCADE", async () => {
+    const serverSourceRoot = new URL("../", import.meta.url).pathname;
+    const migrationsRoot = new URL(
+      "../../../../packages/database/drizzle/",
+      import.meta.url,
+    ).pathname;
+    const durableJobChildTables = new Set<string>();
+    const harnesses: string[] = [];
+
+    for await (const path of migrationFiles.scan(migrationsRoot)) {
+      const migration = await Bun.file(`${migrationsRoot}/${path}`).text();
+      for (const match of migration.matchAll(
+        /ALTER TABLE "([^"]+)" ADD CONSTRAINT [^\n]+ REFERENCES "public"\."durable_jobs"/g,
+      )) {
+        durableJobChildTables.add(match[1]!);
+      }
+    }
+    expect(durableJobChildTables).toContain("client_agent_workflow_artifacts");
+
+    for await (const path of integrationFiles.scan(serverSourceRoot)) {
+      const source = await Bun.file(`${serverSourceRoot}/${path}`).text();
+      if (!source.toLowerCase().includes("truncate table")) continue;
+      if (!source.includes("durable_jobs")) continue;
+
+      harnesses.push(path);
+      const cleanup = source.match(
+        /`(?=[^`]*truncate table)(?=[^`]*durable_jobs)[^`]+`/is,
+      )?.[0];
+      expect(cleanup, `${path} 缺少可审计的显式清理 SQL`).toBeDefined();
+      for (const childTable of durableJobChildTables) {
+        expect(cleanup, `${path} 缺少 ${childTable}`).toContain(childTable);
+      }
+      expect(cleanup, `${path} 不得用 CASCADE 掩盖清理闭包漂移`).not.toMatch(
+        /\bcascade\b/i,
+      );
+    }
+
+    expect(
+      harnesses.length,
+      "至少应发现一个 durable_jobs 清理 harness",
+    ).toBeGreaterThan(0);
+    for (const coreHarness of [
+      "jobs/drizzle-execution.integration.test.ts",
+      "jobs/drizzle-repository.integration.test.ts",
+      "workflow/drizzle-repository.integration.test.ts",
+    ]) {
+      expect(harnesses, `缺少核心清理 harness：${coreHarness}`).toContain(
+        coreHarness,
+      );
+    }
+  });
+});

package/template/apps/server/src/jobs/worker.ts

@@ -4,6 +4,7 @@ import type {
   LeaseResult,
   ManualJobRecovery,
 } from "./execution-repository.js";
+import { createDurableArtifactPublisher } from "./artifact-publisher.js";
 import {
   DurableHandlerError,
   type DurableHandlerContext,
@@ -158,20 +159,13 @@ export class DurableJobWorker {
           );
           assertLease(result, abort);
         },
-        publishArtifact: async (artifact) => {
-          const result = await this.repository.publishArtifact(
-            identity,
-            {
-              id: Bun.randomUUIDv7(),
-              jobId: identity.jobId,
-              stageId: identity.stageId,
-              ...artifact,
-              createdAt: this.now().toISOString(),
-            },
-            this.now(),
-          );
-          assertLease(result, abort);
-        },
+        ...createDurableArtifactPublisher({
+          repository: this.repository,
+          identity,
+          stageKey: claim.stage.key,
+          now: this.now,
+          assertLease: (result) => assertLease(result, abort),
+        }),
       };
       await Promise.race([
         (async () => {

package/template/apps/server/src/license/pairing-service.test.ts

@@ -48,7 +48,7 @@ describe("License 手机配对会话", () => {
 
     const tampered = {
       ...fixture.license,
-      signature: `A${fixture.license.signature.slice(1)}`,
+      signature: `${fixture.license.signature.startsWith("A") ? "B" : "A"}${fixture.license.signature.slice(1)}`,
     };
     await expect(
       service.deliver(

package/template/apps/server/src/module-host/agent-session-memory-port.ts

@@ -0,0 +1,91 @@
+import {
+  MODULE_AGENT_SESSION_MEMORY_SCHEMA_VERSION,
+  type ModuleAgentSessionMemoryPortV1,
+  type ModuleSessionMemorySourceV1,
+} from "@southwind-ai/server-sdk";
+import type { RequestGuardContext } from "../guards.js";
+import type { ContextSourceReference } from "../agent/context-memory/contracts.js";
+import type { MemoryProjectionTriggerPort } from "../agent/context-memory/memory-projector.js";
+
+export function createModuleAgentSessionMemoryPort(
+  moduleName: string,
+  context: RequestGuardContext,
+  signal: AbortSignal,
+  projector: MemoryProjectionTriggerPort,
+): ModuleAgentSessionMemoryPortV1 {
+  const common = (input: ModuleMemoryBase) => ({
+    triggerId: `${moduleName}:${input.triggerId}`,
+    derivation: {
+      sessionId: input.sessionId,
+      throughSequence: input.throughSequence,
+    },
+    sources: input.sources.map((source) => sourceReference(moduleName, source)),
+    ...(input.expiresAt ? { expiresAt: input.expiresAt } : {}),
+  });
+  return {
+    schemaVersion: MODULE_AGENT_SESSION_MEMORY_SCHEMA_VERSION,
+    async rememberUserPreference(input) {
+      return receipt(await projector.projectUserPreference({
+        ...common(input),
+        kind: "user-preference",
+        actorId: context.actor.id,
+        preferenceKey: input.preferenceKey,
+        value: input.value,
+      }, context, signal));
+    },
+    async proposeCaseMemory(input) {
+      return receipt(await projector.projectCaseMemoryCandidate({
+        ...common(input),
+        kind: "case-memory-candidate",
+        caseId: input.caseId,
+        claim: input.claim,
+        ...(input.confidence !== undefined
+          ? { confidence: input.confidence }
+          : {}),
+      }, context, signal));
+    },
+    async referenceVerifiedFact(input) {
+      return receipt(await projector.projectVerifiedFactReference({
+        ...common(input),
+        kind: "verified-fact-reference",
+        caseId: input.caseId,
+        fact: { moduleKey: moduleName, ...input.fact },
+      }, context, signal));
+    },
+  };
+}
+
+interface ModuleMemoryBase {
+  readonly triggerId: string;
+  readonly sessionId: string;
+  readonly throughSequence: number;
+  readonly sources: readonly ModuleSessionMemorySourceV1[];
+  readonly expiresAt?: string;
+}
+
+function sourceReference(
+  moduleName: string,
+  source: ModuleSessionMemorySourceV1,
+): ContextSourceReference {
+  return {
+    moduleKey: moduleName,
+    kind: source.kind as ContextSourceReference["kind"],
+    id: source.id,
+    version: source.version,
+    sequence: source.sequence,
+    digest: source.digest,
+    validity: {
+      status: "valid",
+      checkedAt: source.checkedAt,
+      ...(source.expiresAt ? { expiresAt: source.expiresAt } : {}),
+    },
+  };
+}
+
+function receipt(projection: { memoryId: string; version: string; digest: string }) {
+  return {
+    memoryId: projection.memoryId,
+    version: projection.version,
+    digest: projection.digest,
+  };
+}