create-windy 0.6.12 → 0.6.14

package/template/apps/server/src/agent/context-memory/memory-retrieval-policy.ts

@@ -0,0 +1,195 @@
+import { isServerScopeContext } from "../../data-access/context.js";
+import {
+  MEMORY_KINDS,
+  ContextMemoryError,
+  type AuthorizationDecision,
+  type MemoryCapabilityAuthorizer,
+  type MemoryProjection,
+  type MemoryRetrievalRequest,
+} from "./contracts.js";
+import { sha256 } from "./digest.js";
+import { memoryProjectionContent } from "./memory-content.js";
+
+export function validateMemoryRetrievalRequest(
+  request: MemoryRetrievalRequest,
+): void {
+  if (
+    !request.query?.trim() ||
+    request.query.length > 500 ||
+    !request.sessionId?.trim() ||
+    (request.caseId !== undefined && !request.caseId.trim()) ||
+    !request.permissionKey?.trim() ||
+    !request.feature?.key?.trim() ||
+    !Number.isSafeInteger(request.limit) ||
+    request.limit < 1 ||
+    request.limit > 50 ||
+    !request.kinds.length ||
+    new Set(request.kinds).size !== request.kinds.length ||
+    request.kinds.some((kind) => !MEMORY_KINDS.includes(kind)) ||
+    !isServerScopeContext(request.guardContext?.actor?.scopeContext)
+  ) {
+    throw new ContextMemoryError(
+      "INVALID_REQUEST",
+      "Agent Memory 检索请求无效",
+    );
+  }
+}
+
+export function validCapabilityDecision(
+  value: Awaited<ReturnType<MemoryCapabilityAuthorizer["authorize"]>>,
+): boolean {
+  return (
+    validAuthorizationDecision(value.actor) &&
+    validAuthorizationDecision(value.scope) &&
+    validAuthorizationDecision(value.feature) &&
+    validAuthorizationDecision(value.permission) &&
+    validAuthorizationDecision(value.license) &&
+    value.allowed ===
+      [
+        value.actor,
+        value.scope,
+        value.feature,
+        value.permission,
+        value.license,
+      ].every(({ allowed }) => allowed)
+  );
+}
+
+export function validAuthorizationDecision(
+  value: AuthorizationDecision,
+): boolean {
+  return (
+    value !== undefined &&
+    typeof value.allowed === "boolean" &&
+    typeof value.reason === "string" &&
+    value.reason.length > 0
+  );
+}
+
+export function validMemoryProjection(value: MemoryProjection): boolean {
+  if (
+    !value.memoryId?.trim() ||
+    !value.version?.trim() ||
+    !/^[a-f0-9]{64}$/.test(value.digest) ||
+    value.digest !== sha256(memoryProjectionContent(value)) ||
+    !Number.isFinite(Date.parse(value.createdAt)) ||
+    !value.derivation?.sessionId?.trim() ||
+    (value.currentCaseId !== undefined &&
+      (!value.currentCaseId.trim() || value.currentCaseId.length > 160)) ||
+    !Number.isSafeInteger(value.derivation.throughSequence) ||
+    value.derivation.throughSequence < 1 ||
+    value.validity.status !== "valid" ||
+    !Number.isFinite(Date.parse(value.validity.checkedAt)) ||
+    !value.sources.length ||
+    value.sources.some(
+      (source) =>
+        !source.moduleKey.trim() ||
+        !source.id.trim() ||
+        !source.version.trim() ||
+        !Number.isSafeInteger(source.sequence) ||
+        source.sequence < 1 ||
+        !/^[a-f0-9]{64}$/.test(source.digest) ||
+        source.validity.status !== "valid" ||
+        !Number.isFinite(Date.parse(source.validity.checkedAt)),
+    )
+  )
+    return false;
+  if (
+    value.kind === "working-context" &&
+    !Number.isFinite(Date.parse(value.expiresAt))
+  )
+    return false;
+  if (value.kind === "session-summary") {
+    return Number.isSafeInteger(value.coveredThroughSequence);
+  }
+  if (value.kind === "case-memory-candidate") {
+    return (
+      value.reviewStatus === "pending" &&
+      value.sources.some(({ moduleKey }) => moduleKey !== "system.agent") &&
+      (value.confidence === undefined ||
+        (Number.isFinite(value.confidence) &&
+          value.confidence >= 0 &&
+          value.confidence <= 1))
+    );
+  }
+  if (value.kind === "verified-fact-reference") {
+    return (
+      Boolean(value.fact?.moduleKey?.trim()) &&
+      Boolean(value.fact.resourceType?.trim()) &&
+      Boolean(value.fact.resourceId?.trim()) &&
+      Boolean(value.fact.version?.trim()) &&
+      /^[a-f0-9]{64}$/.test(value.fact.digest) &&
+      value.sources.some(
+        (source) =>
+          source.moduleKey === value.fact.moduleKey &&
+          source.id === value.fact.resourceId &&
+          source.version === value.fact.version &&
+          source.digest === value.fact.digest,
+      )
+    );
+  }
+  return true;
+}
+
+export function memoryTtlDecision(
+  projection: MemoryProjection,
+  now: Date,
+): AuthorizationDecision {
+  const expiries = [
+    projection.expiresAt,
+    projection.validity.expiresAt,
+    ...projection.sources.map(({ validity }) => validity.expiresAt),
+  ].filter((value): value is string => value !== undefined);
+  if (!expiries.length) return { allowed: true, reason: "no-expiry" };
+  const invalid = expiries.some(
+    (value) =>
+      !Number.isFinite(Date.parse(value)) || Date.parse(value) <= now.getTime(),
+  );
+  return invalid
+    ? { allowed: false, reason: "expired" }
+    : { allowed: true, reason: "valid" };
+}
+
+export function memoryInCurrentScope(
+  projection: MemoryProjection,
+  request: MemoryRetrievalRequest,
+): boolean {
+  if (valueHasDifferentCase(projection, request.caseId)) return false;
+  if (
+    projection.kind === "working-context" ||
+    projection.kind === "session-summary"
+  ) {
+    return (
+      projection.scope.kind === "session" &&
+      projection.scope.sessionId === request.sessionId &&
+      projection.derivation.sessionId === request.sessionId
+    );
+  }
+  if (projection.kind === "user-preference") {
+    return (
+      projection.scope.kind === "user" &&
+      projection.scope.actorId === request.guardContext.actor.id
+    );
+  }
+  return (
+    projection.scope.kind === "case" &&
+    request.caseId !== undefined &&
+    projection.scope.caseId === request.caseId
+  );
+}
+
+function valueHasDifferentCase(
+  projection: MemoryProjection,
+  currentCaseId: string | undefined,
+) {
+  return (
+    projection.currentCaseId !== undefined &&
+    projection.currentCaseId !== currentCaseId
+  );
+}
+
+export function hasDuplicateMemoryIds(
+  items: readonly { memoryId: string }[],
+): boolean {
+  return new Set(items.map(({ memoryId }) => memoryId)).size !== items.length;
+}

package/template/apps/server/src/agent/context-memory/memory-retriever.test.ts

@@ -0,0 +1,339 @@
+import { describe, expect, test } from "bun:test";
+import { featureKey, type FeatureFlagDefinition } from "@southwind-ai/shared";
+import { buildScopeContext } from "../../data-access/context.js";
+import type { RequestGuardContext } from "../../guards.js";
+import { createServerRuntime } from "../../runtime.js";
+import type {
+  CaseMemoryCandidate,
+  MemoryCapabilityDecision,
+  MemoryKind,
+  MemoryProjection,
+  MemoryRetrievalRequest,
+  UserPreferenceMemory,
+  VerifiedFactReferenceMemory,
+} from "./contracts.js";
+import { sha256 } from "./digest.js";
+import { AccessGuardMemoryCapabilityAuthorizer } from "./memory-authorization.js";
+import {
+  GovernedMemoryRetriever,
+  memoryProjectionContent,
+} from "./memory-retriever.js";
+
+describe("Governed Memory Retriever", () => {
+  test("只返回当前案件候选且不会把候选自动晋升为业务事实", async () => {
+    const values = new Map<string, MemoryProjection>([
+      ["current", candidate("current", "case-1")],
+      ["other-case", candidate("other-case", "case-2")],
+      [
+        "expired",
+        candidate("expired", "case-1", {
+          expiresAt: "2026-08-26T23:59:59.000Z",
+        }),
+      ],
+      ["denied", fact("denied", "case-1")],
+      [
+        "invalid",
+        { ...candidate("invalid", "case-1"), digest: "0".repeat(64) },
+      ],
+    ]);
+    const retriever = new GovernedMemoryRetriever(
+      { authorize: async () => allowedCapability() },
+      {
+        search: async () =>
+          [...values.keys()].map((memoryId, score) => ({ memoryId, score })),
+      },
+      { read: async (memoryId) => values.get(memoryId) },
+      {
+        authorize: async (projection) => ({
+          allowed: projection.memoryId !== "denied",
+          reason:
+            projection.memoryId === "denied" ? "object-denied" : "allowed",
+        }),
+      },
+      { now: () => new Date("2026-08-27T00:00:00.000Z") },
+    );
+    const result = await retriever.retrieve(
+      request(["case-memory-candidate", "verified-fact-reference"]),
+      new AbortController().signal,
+    );
+
+    expect(result.items).toHaveLength(1);
+    expect(result.items[0]!.projection).toMatchObject({
+      memoryId: "current",
+      kind: "case-memory-candidate",
+      reviewStatus: "pending",
+      scope: { kind: "case", caseId: "case-1" },
+    });
+    expect("fact" in result.items[0]!.projection).toBeFalse();
+    expect(result.excluded).toEqual({
+      missing: 0,
+      objectDenied: 1,
+      expired: 1,
+      outOfScope: 1,
+      invalid: 1,
+    });
+    expect(Object.isFrozen(result.items[0]!.projection)).toBeTrue();
+  });
+
+  test("案件坐标缺失时不合并任何案件 Memory", async () => {
+    const projection = candidate("candidate-1", "case-1");
+    const retriever = retrieverFor([projection]);
+    const input = { ...request([projection.kind]), caseId: undefined };
+
+    const result = await retriever.retrieve(
+      input,
+      new AbortController().signal,
+    );
+    expect(result.items).toEqual([]);
+    expect(result.excluded.outOfScope).toBe(1);
+  });
+
+  test("User Preference 只能回到所属 Actor", async () => {
+    const projection = preference("preference-1", "another-actor");
+    const result = await retrieverFor([projection]).retrieve(
+      request([projection.kind]),
+      new AbortController().signal,
+    );
+    expect(result.items).toEqual([]);
+    expect(result.excluded.outOfScope).toBe(1);
+  });
+
+  test("带案件亲和性的 Session Memory 不进入其它案件", async () => {
+    const projection = withDigest({
+      ...preference("preference-case-1", "actor-1"),
+      digest: "",
+      currentCaseId: "case-1",
+    });
+    const input = { ...request([projection.kind]), caseId: "case-2" };
+
+    const result = await retrieverFor([projection]).retrieve(
+      input,
+      new AbortController().signal,
+    );
+    expect(result.items).toEqual([]);
+    expect(result.excluded.outOfScope).toBe(1);
+  });
+
+  test("Capability 拒绝发生在 Search 之前且授权异常 fail closed", async () => {
+    let searches = 0;
+    const denied = new GovernedMemoryRetriever(
+      {
+        authorize: async () => ({
+          ...allowedCapability(),
+          allowed: false,
+          permission: { allowed: false, reason: "missing-permission" },
+        }),
+      },
+      {
+        search: async () => {
+          searches += 1;
+          return [];
+        },
+      },
+      { read: async () => undefined },
+      { authorize: async () => ({ allowed: true, reason: "allowed" }) },
+    );
+    await expect(
+      denied.retrieve(
+        request(["session-summary"]),
+        new AbortController().signal,
+      ),
+    ).rejects.toMatchObject({ code: "AUTHORIZATION_DENIED" });
+    expect(searches).toBe(0);
+
+    const unavailable = retrieverFor([candidate("candidate-1", "case-1")], {
+      authorize: async () => Promise.reject(new Error("policy store down")),
+    });
+    await expect(
+      unavailable.retrieve(
+        request(["case-memory-candidate"]),
+        new AbortController().signal,
+      ),
+    ).rejects.toMatchObject({ code: "AUTHORIZATION_UNAVAILABLE" });
+  });
+
+  test("Access Guard adapter 同时执行 Feature Permission License 与 Scope", async () => {
+    const authorizer = new AccessGuardMemoryCapabilityAuthorizer(
+      createServerRuntime({ NODE_ENV: "development" }),
+    );
+    const allowed = await authorizer.authorize(request(["session-summary"]));
+    expect(allowed).toMatchObject({
+      allowed: true,
+      actor: { allowed: true },
+      scope: { allowed: true },
+      feature: { allowed: true },
+      permission: { allowed: true },
+      license: { allowed: true },
+    });
+
+    const deniedRequest = request(["session-summary"]);
+    deniedRequest.guardContext.actor.permissionKeys = [];
+    const denied = await authorizer.authorize(deniedRequest);
+    expect(denied.allowed).toBeFalse();
+    expect(denied.permission.reason).toBe("missing-permission");
+  });
+});
+
+function retrieverFor(
+  projections: readonly MemoryProjection[],
+  objects = {
+    authorize: async () => ({ allowed: true, reason: "allowed" }),
+  },
+) {
+  const values = new Map(projections.map((item) => [item.memoryId, item]));
+  return new GovernedMemoryRetriever(
+    { authorize: async () => allowedCapability() },
+    {
+      search: async () => projections.map(({ memoryId }) => ({ memoryId })),
+    },
+    { read: async (memoryId) => values.get(memoryId) },
+    objects,
+  );
+}
+
+function request(kinds: readonly MemoryKind[]): MemoryRetrievalRequest {
+  return {
+    query: "案件线索",
+    sessionId: "session-1",
+    caseId: "case-1",
+    kinds,
+    limit: 10,
+    feature: feature(),
+    permissionKey: "system.agent-session.read",
+    guardContext: guardContext(),
+  };
+}
+
+function guardContext(): RequestGuardContext {
+  return {
+    requestId: "request-1",
+    startedAt: "2026-08-27T00:00:00.000Z",
+    actor: {
+      id: "actor-1",
+      type: "user",
+      name: "办案人员",
+      roleCodes: ["operator"],
+      permissionKeys: ["system.agent-session.read"],
+      scopeContext: buildScopeContext("actor-1", "department-1", [
+        {
+          id: "role-1",
+          code: "operator",
+          dataScope: "self",
+          departmentIds: [],
+        },
+      ]),
+    },
+  };
+}
+
+function feature(): FeatureFlagDefinition {
+  return {
+    key: featureKey("system.agent-session"),
+    label: "Agent Memory",
+    module: "system",
+    visible: "visible",
+    enabled: true,
+    stage: "stable",
+  };
+}
+
+function allowedCapability(): MemoryCapabilityDecision {
+  const allowed = { allowed: true, reason: "allowed" };
+  return {
+    allowed: true,
+    actor: allowed,
+    scope: allowed,
+    feature: allowed,
+    permission: allowed,
+    license: allowed,
+  };
+}
+
+function candidate(
+  memoryId: string,
+  caseId: string,
+  overrides: Partial<CaseMemoryCandidate> = {},
+): CaseMemoryCandidate {
+  return withDigest({
+    memoryId,
+    kind: "case-memory-candidate",
+    version: "1",
+    digest: "",
+    scope: { kind: "case", caseId },
+    sources: [source("artifact-summary", `artifact-${memoryId}`, "evidence")],
+    validity: validity(),
+    derivation: { sessionId: "session-test", throughSequence: 1 },
+    createdAt: "2026-08-26T00:00:00.000Z",
+    claim: "待核验线索",
+    reviewStatus: "pending",
+    confidence: 0.8,
+    ...overrides,
+  });
+}
+
+function fact(memoryId: string, caseId: string): VerifiedFactReferenceMemory {
+  return withDigest({
+    memoryId,
+    kind: "verified-fact-reference",
+    version: "1",
+    digest: "",
+    scope: { kind: "case", caseId },
+    sources: [source("artifact-summary", `artifact-${memoryId}`, "evidence")],
+    validity: validity(),
+    derivation: { sessionId: "session-test", throughSequence: 1 },
+    createdAt: "2026-08-26T00:00:00.000Z",
+    fact: {
+      moduleKey: "evidence",
+      resourceType: "evidence.fact",
+      resourceId: `artifact-${memoryId}`,
+      version: "1",
+      digest: "b".repeat(64),
+    },
+  });
+}
+
+function preference(memoryId: string, actorId: string): UserPreferenceMemory {
+  return withDigest({
+    memoryId,
+    kind: "user-preference",
+    version: "1",
+    digest: "",
+    scope: { kind: "user", actorId },
+    sources: [source("recent-event", "event-preference")],
+    validity: validity(),
+    derivation: { sessionId: "session-test", throughSequence: 1 },
+    createdAt: "2026-08-26T00:00:00.000Z",
+    preferenceKey: "display.density",
+    value: "compact",
+  });
+}
+
+function source(
+  kind: "artifact-summary" | "recent-event",
+  id: string,
+  moduleKey = "system.agent",
+) {
+  return {
+    moduleKey,
+    kind,
+    id,
+    version: "1",
+    sequence: 1,
+    digest: "b".repeat(64),
+    validity: validity(),
+  } as const;
+}
+
+function validity() {
+  return {
+    status: "valid" as const,
+    checkedAt: "2026-08-27T00:00:00.000Z",
+  };
+}
+
+function withDigest<T extends MemoryProjection>(projection: T): T {
+  return {
+    ...projection,
+    digest: sha256(memoryProjectionContent(projection)),
+  };
+}

package/template/apps/server/src/agent/context-memory/memory-retriever.ts

@@ -0,0 +1,184 @@
+import {
+  ContextMemoryError,
+  type GovernedMemoryResult,
+  type MemoryCapabilityAuthorizer,
+  type MemoryObjectAuthorizationPort,
+  type MemoryProjectionPort,
+  type MemoryRetrievalRequest,
+  type MemoryRetrievalResult,
+  type MemorySearchPort,
+} from "./contracts.js";
+export { memoryProjectionContent } from "./memory-content.js";
+import {
+  hasDuplicateMemoryIds,
+  memoryInCurrentScope,
+  memoryTtlDecision,
+  validAuthorizationDecision,
+  validCapabilityDecision,
+  validMemoryProjection,
+  validateMemoryRetrievalRequest,
+} from "./memory-retrieval-policy.js";
+
+export interface GovernedMemoryRetrieverOptions {
+  readonly now?: () => Date;
+}
+
+export class GovernedMemoryRetriever {
+  readonly #now: () => Date;
+
+  constructor(
+    private readonly capability: MemoryCapabilityAuthorizer,
+    private readonly search: MemorySearchPort,
+    private readonly projections: MemoryProjectionPort,
+    private readonly objects: MemoryObjectAuthorizationPort,
+    options: GovernedMemoryRetrieverOptions = {},
+  ) {
+    this.#now = options.now ?? (() => new Date());
+  }
+
+  async retrieve(
+    request: MemoryRetrievalRequest,
+    signal: AbortSignal,
+  ): Promise<MemoryRetrievalResult> {
+    validateMemoryRetrievalRequest(request);
+    let capability;
+    try {
+      capability = await this.capability.authorize(request);
+    } catch {
+      throw authorizationUnavailable();
+    }
+    if (!validCapabilityDecision(capability) || !capability.allowed) {
+      throw new ContextMemoryError(
+        "AUTHORIZATION_DENIED",
+        "当前 Actor 无权检索 Agent Memory",
+      );
+    }
+    let hits;
+    try {
+      hits = await this.search.search(
+        request.query,
+        request.limit,
+        request.guardContext.actor,
+        request.guardContext.requestId,
+        signal,
+        {
+          sessionId: request.sessionId,
+          ...(request.caseId ? { caseId: request.caseId } : {}),
+          kinds: request.kinds,
+        },
+      );
+    } catch (error) {
+      if (error instanceof ContextMemoryError) throw error;
+      throw new ContextMemoryError(
+        "SOURCE_UNAVAILABLE",
+        "Agent Memory 检索暂不可用",
+      );
+    }
+    if (hits.length > request.limit || hasDuplicateMemoryIds(hits)) {
+      throw invalidProjection("Agent Memory 检索结果无效");
+    }
+
+    const excluded = {
+      missing: 0,
+      objectDenied: 0,
+      expired: 0,
+      outOfScope: 0,
+      invalid: 0,
+    };
+    const items: GovernedMemoryResult[] = [];
+    for (const hit of hits) {
+      if (signal.aborted) {
+        throw new ContextMemoryError(
+          "SOURCE_UNAVAILABLE",
+          "Agent Memory 检索已取消",
+        );
+      }
+      let projection;
+      try {
+        projection = await this.projections.read(
+          hit.memoryId,
+          request.guardContext,
+          signal,
+        );
+      } catch {
+        throw new ContextMemoryError(
+          "SOURCE_UNAVAILABLE",
+          "Agent Memory 投影暂不可用",
+        );
+      }
+      if (!projection) {
+        excluded.missing += 1;
+        continue;
+      }
+      if (!validMemoryProjection(projection)) {
+        excluded.invalid += 1;
+        continue;
+      }
+      if (!request.kinds.includes(projection.kind)) {
+        excluded.outOfScope += 1;
+        continue;
+      }
+      const ttl = memoryTtlDecision(projection, this.#now());
+      if (!ttl.allowed) {
+        excluded.expired += 1;
+        continue;
+      }
+      if (!memoryInCurrentScope(projection, request)) {
+        excluded.outOfScope += 1;
+        continue;
+      }
+      let objectDecision;
+      try {
+        objectDecision = await this.objects.authorize(
+          projection,
+          request.guardContext,
+          signal,
+        );
+      } catch {
+        throw authorizationUnavailable();
+      }
+      if (!validAuthorizationDecision(objectDecision)) {
+        throw authorizationUnavailable();
+      }
+      if (!objectDecision.allowed) {
+        excluded.objectDenied += 1;
+        continue;
+      }
+      items.push(
+        immutableClone({
+          projection,
+          ...(hit.score !== undefined ? { score: hit.score } : {}),
+          authorization: {
+            capability,
+            object: objectDecision,
+            ttl,
+          },
+        }),
+      );
+    }
+    return immutableClone({ items, excluded });
+  }
+}
+
+function immutableClone<T>(value: T): T {
+  return deepFreeze(structuredClone(value));
+}
+
+function deepFreeze<T>(value: T): T {
+  if (!value || typeof value !== "object" || Object.isFrozen(value)) return value;
+  for (const child of Object.values(value as Record<string, unknown>)) {
+    deepFreeze(child);
+  }
+  return Object.freeze(value);
+}
+
+function invalidProjection(message: string): ContextMemoryError {
+  return new ContextMemoryError("INVALID_PROJECTION", message);
+}
+
+function authorizationUnavailable(): ContextMemoryError {
+  return new ContextMemoryError(
+    "AUTHORIZATION_UNAVAILABLE",
+    "Agent Memory 授权暂不可用",
+  );
+}