create-windy 0.6.12 → 0.6.14

package/template/apps/server/src/agent/session-invalidation/dispatcher.contract.test.ts

@@ -0,0 +1,333 @@
+import { describe, expect, test } from "bun:test";
+import {
+  SOURCE_INVALIDATION_PROJECTION_TARGETS,
+  type AuthoritativeSourceAccessPort,
+  type SourceInvalidationDelivery,
+  type SourceInvalidationEnvelopeV1,
+  type SourceInvalidationProjectionPort,
+  type SourceInvalidationProjectionPorts,
+  type SourceInvalidationProjectionTarget,
+} from "./contracts.js";
+import {
+  SourceInvalidationDispatcher,
+  SourceInvalidationProtocolError,
+  sourceInvalidationDeliveryId,
+} from "./dispatcher.js";
+import {
+  requireAuthoritativeSourceRead,
+  SourceReadDeniedError,
+} from "./read-guard.js";
+import { sessionArchiveInvalidation } from "./test-envelopes.js";
+
+describe("SourceInvalidationDispatcher contract", () => {
+  test("routes every projection independently with a stable delivery id", async () => {
+    const seen: string[] = [];
+    const dispatcher = new SourceInvalidationDispatcher(ports(seen));
+
+    for (const target of SOURCE_INVALIDATION_PROJECTION_TARGETS) {
+      const delivery = deliveryFor(revocation(), target);
+      expect(await dispatcher.dispatch(delivery)).toBe("applied");
+    }
+
+    expect(seen).toEqual(
+      SOURCE_INVALIDATION_PROJECTION_TARGETS.map(
+        (target) => `${target}:invalidate-7:${target}`,
+      ),
+    );
+  });
+
+  test("lets sinks converge duplicate and stale deliveries idempotently", async () => {
+    const sink = new MonotonicProjectionPort();
+    const dispatcher = new SourceInvalidationDispatcher({
+      ...ports([]),
+      context: sink,
+    });
+    const current = revocation();
+    const stale = {
+      ...current,
+      invalidationId: "invalidate-6",
+      source: { ...current.source, sequence: 6 },
+    } as SourceInvalidationEnvelopeV1;
+
+    expect(await dispatcher.dispatch(deliveryFor(current, "context"))).toBe(
+      "applied",
+    );
+    expect(await dispatcher.dispatch(deliveryFor(current, "context"))).toBe(
+      "duplicate",
+    );
+    expect(await dispatcher.dispatch(deliveryFor(stale, "context"))).toBe(
+      "stale",
+    );
+  });
+
+  test("preserves deletion, archive and invalidation target states", async () => {
+    const seen: string[] = [];
+    const dispatcher = new SourceInvalidationDispatcher(ports(seen));
+    const transitions = [
+      { reason: "source-deleted", targetState: "deleted" },
+      { reason: "source-archived", targetState: "archived" },
+      { reason: "source-invalidated", targetState: "invalid" },
+    ] as const;
+
+    for (const [index, transition] of transitions.entries()) {
+      const envelope = resourceInvalidation(index + 8, transition);
+      expect(await dispatcher.dispatch(deliveryFor(envelope, "memory"))).toBe(
+        "applied",
+      );
+    }
+
+    expect(seen).toEqual([
+      "memory:invalidate-8:memory",
+      "memory:invalidate-9:memory",
+      "memory:invalidate-10:memory",
+    ]);
+  });
+
+  test("rejects projection deletion disguised as authoritative source deletion", async () => {
+    const seen: string[] = [];
+    const dispatcher = new SourceInvalidationDispatcher(ports(seen));
+    const envelope = {
+      ...resourceInvalidation(11, {
+        reason: "source-deleted",
+        targetState: "deleted",
+      }),
+      causedBy: {
+        kind: "domain-event",
+        eventId: "memory-projection-delete-11",
+        eventSequence: 11,
+      },
+    } as SourceInvalidationEnvelopeV1;
+
+    await expect(
+      dispatcher.dispatch(deliveryFor(envelope, "memory")),
+    ).rejects.toThrow("权威生命周期事件");
+    expect(seen).toEqual([]);
+  });
+
+  test("routes session archive as a dedicated derived-projection scope", async () => {
+    const seen: string[] = [];
+    const dispatcher = new SourceInvalidationDispatcher(ports(seen));
+    const envelope = sessionArchiveInvalidation();
+
+    await expect(
+      dispatcher.dispatch(deliveryFor(envelope, "context")),
+    ).resolves.toBe("applied");
+    expect(envelope.scope).toEqual({
+      kind: "session-derived",
+      sessionId: "session-1",
+    });
+  });
+
+  test("rejects malformed causal coordinates before touching a sink", async () => {
+    const seen: string[] = [];
+    const dispatcher = new SourceInvalidationDispatcher(ports(seen));
+    const envelope = {
+      ...revocation(),
+      causedBy: {
+        kind: "session-event",
+        eventId: "event-7",
+        eventSequence: 7,
+      },
+    } as SourceInvalidationEnvelopeV1;
+
+    await expect(
+      dispatcher.dispatch(deliveryFor(envelope, "search")),
+    ).rejects.toBeInstanceOf(SourceInvalidationProtocolError);
+    expect(seen).toEqual([]);
+  });
+});
+
+describe("authoritative source read contract", () => {
+  test("allows only an exact current source and authorization generation", async () => {
+    const query = readQuery();
+    const port: AuthoritativeSourceAccessPort = {
+      authorizeCurrent: async () => ({
+        outcome: "allowed",
+        sourceVersion: query.source.version,
+        sourceSequence: query.source.sequence,
+        authorizationGeneration: query.authorization.generation,
+      }),
+    };
+
+    await expect(requireAuthoritativeSourceRead(port, query)).resolves.toEqual({
+      outcome: "allowed",
+      sourceVersion: "source-v3",
+      sourceSequence: 7,
+      authorizationGeneration: 4,
+    });
+  });
+
+  test("revocation fails closed before asynchronous projections converge", async () => {
+    const projectionWasInvalidated = false;
+    const port: AuthoritativeSourceAccessPort = {
+      authorizeCurrent: async () => ({
+        outcome: "denied",
+        reason: "authorization-revoked",
+      }),
+    };
+
+    await expect(
+      requireAuthoritativeSourceRead(port, readQuery()),
+    ).rejects.toBeInstanceOf(SourceReadDeniedError);
+    expect(projectionWasInvalidated).toBe(false);
+  });
+
+  test("authority failure and stale coordinates are indistinguishable denials", async () => {
+    const unavailable: AuthoritativeSourceAccessPort = {
+      authorizeCurrent: async () => {
+        throw new Error("database unavailable");
+      },
+    };
+    const stale: AuthoritativeSourceAccessPort = {
+      authorizeCurrent: async () => ({
+        outcome: "allowed",
+        sourceVersion: "source-v4",
+        sourceSequence: 8,
+        authorizationGeneration: 5,
+      }),
+    };
+
+    await expect(
+      requireAuthoritativeSourceRead(unavailable, readQuery()),
+    ).rejects.toThrow("来源不存在或不可访问");
+    await expect(
+      requireAuthoritativeSourceRead(stale, readQuery()),
+    ).rejects.toThrow("来源不存在或不可访问");
+  });
+});
+
+class MonotonicProjectionPort
+  implements SourceInvalidationProjectionPort<"context">
+{
+  readonly target = "context" as const;
+  private readonly applied = new Set<string>();
+  private sequence = 0;
+
+  async invalidate(input: {
+    readonly deliveryId: string;
+    readonly envelope: SourceInvalidationEnvelopeV1;
+  }) {
+    if (this.applied.has(input.deliveryId)) return "duplicate" as const;
+    if (input.envelope.source.sequence < this.sequence) return "stale" as const;
+    this.applied.add(input.deliveryId);
+    this.sequence = input.envelope.source.sequence;
+    return "applied" as const;
+  }
+}
+
+function ports(seen: string[]): SourceInvalidationProjectionPorts {
+  return Object.fromEntries(
+    SOURCE_INVALIDATION_PROJECTION_TARGETS.map((target) => [
+      target,
+      {
+        target,
+        invalidate: async ({ deliveryId }: { readonly deliveryId: string }) => {
+          seen.push(`${target}:${deliveryId}`);
+          return "applied" as const;
+        },
+      },
+    ]),
+  ) as unknown as SourceInvalidationProjectionPorts;
+}
+
+function deliveryFor(
+  envelope: SourceInvalidationEnvelopeV1,
+  target: SourceInvalidationProjectionTarget,
+): SourceInvalidationDelivery {
+  return {
+    deliveryId: sourceInvalidationDeliveryId(
+      envelope.invalidationId,
+      target,
+    ),
+    target,
+    envelope,
+    attempt: 1,
+    leaseToken: `lease-${target}`,
+  };
+}
+
+function revocation(): SourceInvalidationEnvelopeV1 {
+  return {
+    contractVersion: 1,
+    invalidationId: "invalidate-7",
+    source: {
+      moduleKey: "analysis",
+      sourceKind: "evidence-file",
+      sourceId: "file-9",
+      version: "source-v3",
+      sequence: 7,
+      digest: "a".repeat(64),
+    },
+    transition: {
+      reason: "authorization-revoked",
+      targetState: "revoked",
+    },
+    scope: {
+      kind: "authorization",
+      authorization: {
+        actorId: "actor-1",
+        scopeDigest: "scope-4",
+        generation: 4,
+      },
+    },
+    causedBy: {
+      kind: "session-event",
+      eventId: "event-7",
+      eventSequence: 7,
+      sessionId: "session-1",
+    },
+    occurredAt: "2026-08-27T08:00:00.000Z",
+  };
+}
+
+function resourceInvalidation(
+  sequence: number,
+  transition:
+    | { readonly reason: "source-deleted"; readonly targetState: "deleted" }
+    | { readonly reason: "source-archived"; readonly targetState: "archived" }
+    | {
+        readonly reason: "source-invalidated";
+        readonly targetState: "invalid";
+      },
+): SourceInvalidationEnvelopeV1 {
+  const base = revocation();
+  if (transition.reason === "source-deleted") {
+    return {
+      ...base,
+      invalidationId: `invalidate-${sequence}`,
+      source: { ...base.source, sequence },
+      causedBy: {
+        kind: "authoritative-source-lifecycle",
+        authorityModuleKey: base.source.moduleKey,
+        eventId: `event-${sequence}`,
+        eventSequence: sequence,
+      },
+      transition,
+      scope: { kind: "resource" },
+    };
+  }
+  return {
+    ...base,
+    invalidationId: `invalidate-${sequence}`,
+    source: { ...base.source, sequence },
+    causedBy: {
+      kind: "domain-event",
+      eventId: `event-${sequence}`,
+      eventSequence: sequence,
+    },
+    transition,
+    scope: { kind: "resource" },
+  };
+}
+
+function readQuery() {
+  return {
+    source: revocation().source,
+    authorization: {
+      actorId: "actor-1",
+      scopeDigest: "scope-4",
+      generation: 4,
+    },
+    requestId: "request-1",
+  };
+}

package/template/apps/server/src/agent/session-invalidation/dispatcher.ts

@@ -0,0 +1,205 @@
+import {
+  SOURCE_INVALIDATION_CONTRACT_VERSION,
+  type SourceInvalidationDelivery,
+  type SourceInvalidationEnvelopeV1,
+  type SourceInvalidationProjectionPorts,
+  type SourceInvalidationProjectionResult,
+} from "./contracts.js";
+
+export class SourceInvalidationProtocolError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "SourceInvalidationProtocolError";
+  }
+}
+
+export class SourceInvalidationDispatcher {
+  constructor(private readonly ports: SourceInvalidationProjectionPorts) {}
+
+  async dispatch(
+    delivery: SourceInvalidationDelivery,
+  ): Promise<SourceInvalidationProjectionResult> {
+    assertSourceInvalidationEnvelope(delivery.envelope);
+    if (
+      delivery.deliveryId !==
+        sourceInvalidationDeliveryId(
+          delivery.envelope.invalidationId,
+          delivery.target,
+        ) ||
+      !positiveInteger(delivery.attempt) ||
+      !delivery.leaseToken
+    ) {
+      throw new SourceInvalidationProtocolError("传播投递坐标无效");
+    }
+    const port = this.ports[delivery.target];
+    if (!port || port.target !== delivery.target) {
+      throw new SourceInvalidationProtocolError(
+        `传播目标未正确装配：${delivery.target}`,
+      );
+    }
+    return port.invalidate({
+      deliveryId: delivery.deliveryId,
+      envelope: delivery.envelope,
+    });
+  }
+}
+
+export function assertSourceInvalidationEnvelope(
+  envelope: unknown,
+): asserts envelope is SourceInvalidationEnvelopeV1 {
+  if (
+    !envelope ||
+    typeof envelope !== "object" ||
+    !("source" in envelope) ||
+    !envelope.source ||
+    typeof envelope.source !== "object" ||
+    !("causedBy" in envelope) ||
+    !envelope.causedBy ||
+    typeof envelope.causedBy !== "object" ||
+    !("transition" in envelope) ||
+    !envelope.transition ||
+    typeof envelope.transition !== "object" ||
+    !("scope" in envelope) ||
+    !envelope.scope ||
+    typeof envelope.scope !== "object"
+  ) {
+    throw new SourceInvalidationProtocolError("来源失效协议结构无效");
+  }
+  const candidate = envelope as SourceInvalidationEnvelopeV1;
+  if (candidate.contractVersion !== SOURCE_INVALIDATION_CONTRACT_VERSION) {
+    throw new SourceInvalidationProtocolError("来源失效协议版本不受支持");
+  }
+  if (
+    !candidate.invalidationId ||
+    !candidate.source.moduleKey ||
+    !candidate.source.sourceKind ||
+    !candidate.source.sourceId ||
+    !candidate.source.version ||
+    !positiveInteger(candidate.source.sequence) ||
+    !candidate.causedBy.eventId ||
+    !positiveInteger(candidate.causedBy.eventSequence) ||
+    !validCausationKind(candidate.causedBy.kind) ||
+    !validTransition(candidate.transition) ||
+    !validInstant(candidate.occurredAt)
+  ) {
+    throw new SourceInvalidationProtocolError("来源失效因果坐标无效");
+  }
+  if (
+    candidate.source.digest !== undefined &&
+    (typeof candidate.source.digest !== "string" ||
+      !/^[a-f0-9]{64}$/.test(candidate.source.digest))
+  ) {
+    throw new SourceInvalidationProtocolError("来源摘要无效");
+  }
+  if (
+    candidate.causedBy.kind === "session-event" &&
+    !candidate.causedBy.sessionId
+  ) {
+    throw new SourceInvalidationProtocolError("Session 事件缺少 Session ID");
+  }
+  if (
+    candidate.transition.reason === "authorization-revoked" &&
+    (candidate.scope.kind !== "authorization" ||
+      !candidate.scope.authorization ||
+      !candidate.scope.authorization.actorId ||
+      !candidate.scope.authorization.scopeDigest ||
+      !positiveInteger(candidate.scope.authorization.generation))
+  ) {
+    throw new SourceInvalidationProtocolError("撤权传播缺少授权坐标");
+  }
+  if (candidate.causedBy.kind === "authoritative-source-lifecycle") {
+    if (
+      candidate.scope.kind !== "resource" ||
+      candidate.causedBy.authorityModuleKey !== candidate.source.moduleKey ||
+      !isAuthoritativeLifecycleTransition(candidate.transition.reason)
+    ) {
+      throw new SourceInvalidationProtocolError(
+        "来源生命周期必须由所属模块的权威生命周期事件触发",
+      );
+    }
+    return;
+  }
+  if (isAuthoritativeLifecycleTransition(candidate.transition.reason)) {
+    throw new SourceInvalidationProtocolError(
+      "来源生命周期必须由所属模块的权威生命周期事件触发",
+    );
+  }
+  if (candidate.scope.kind === "session-derived") {
+    if (
+      candidate.transition.reason !== "source-archived" ||
+      candidate.source.moduleKey !== "system.agent" ||
+      candidate.source.sourceKind !== "session" ||
+      candidate.source.sourceId !== candidate.scope.sessionId ||
+      candidate.causedBy.kind !== "session-event" ||
+      candidate.causedBy.sessionId !== candidate.scope.sessionId
+    ) {
+      throw new SourceInvalidationProtocolError("Session 派生投影失效范围无效");
+    }
+    return;
+  }
+  if (
+    candidate.transition.reason !== "authorization-revoked" &&
+    candidate.scope.kind !== "resource"
+  ) {
+    throw new SourceInvalidationProtocolError("来源状态传播范围无效");
+  }
+}
+
+export function sourceInvalidationDeliveryId(
+  invalidationId: string,
+  target: SourceInvalidationDelivery["target"],
+): string {
+  return `${invalidationId}:${target}`;
+}
+
+function positiveInteger(value: unknown): value is number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+
+function validInstant(value: unknown): value is string {
+  return typeof value === "string" && Number.isFinite(Date.parse(value));
+}
+
+function validCausationKind(value: unknown): boolean {
+  return (
+    value === "session-event" ||
+    value === "domain-event" ||
+    value === "retention-policy" ||
+    value === "authoritative-source-lifecycle"
+  );
+}
+
+function validTransition(
+  value: unknown,
+): value is SourceInvalidationEnvelopeV1["transition"] {
+  if (!value || typeof value !== "object") return false;
+  const transition = value as {
+    readonly reason?: unknown;
+    readonly targetState?: unknown;
+  };
+  if (transition.reason === "authorization-revoked") {
+    return transition.targetState === "revoked";
+  }
+  if (transition.reason === "source-deleted") {
+    return transition.targetState === "deleted";
+  }
+  if (transition.reason === "source-archived") {
+    return transition.targetState === "archived";
+  }
+  return (
+    (transition.reason === "source-invalidated" ||
+      transition.reason === "source-expired" ||
+      transition.reason === "source-superseded") &&
+    transition.targetState === "invalid"
+  );
+}
+
+function isAuthoritativeLifecycleTransition(
+  reason: SourceInvalidationEnvelopeV1["transition"]["reason"],
+) {
+  return (
+    reason === "source-deleted" ||
+    reason === "source-expired" ||
+    reason === "source-superseded"
+  );
+}

package/template/apps/server/src/agent/session-invalidation/module-authoritative-producer.test.ts

@@ -0,0 +1,127 @@
+import { describe, expect, test } from "bun:test";
+import { ModuleAuthoritativeSourceAccessRegistry } from "../context-memory/authoritative-source-registry.js";
+import type {
+  SourceInvalidationEnvelopeV1,
+  SourceInvalidationAppendResult,
+} from "./contracts.js";
+import { ModuleAuthoritativeInvalidationUnavailableError } from "./module-authoritative-producer.js";
+
+describe("module-authoritative invalidation producer", () => {
+  test("pins module identity and emits each governed transition", async () => {
+    const appended: SourceInvalidationEnvelopeV1[] = [];
+    const registry = authoritativeRegistry();
+    const producer = registry.bindInvalidationProducer({
+      moduleKey: "case.material",
+      authorization: {
+        actorId: "actor-7",
+        scopeDigest: "sha256:scope-9",
+        generation: 4,
+      },
+      append: recordingAppend(appended),
+    });
+
+    await producer.sourceDeleted(input(11));
+    await producer.sourceExpired(input(12));
+    await producer.sourceSuperseded(input(13));
+    await producer.authorizationRevoked(input(14));
+
+    expect(appended.map(({ source }) => source.moduleKey)).toEqual([
+      "case.material",
+      "case.material",
+      "case.material",
+      "case.material",
+    ]);
+    expect(appended.map(({ transition }) => transition.reason)).toEqual([
+      "source-deleted",
+      "source-expired",
+      "source-superseded",
+      "authorization-revoked",
+    ]);
+    expect(appended.slice(0, 3).map(({ causedBy }) => causedBy.kind)).toEqual([
+      "authoritative-source-lifecycle",
+      "authoritative-source-lifecycle",
+      "authoritative-source-lifecycle",
+    ]);
+    expect(appended[3]?.scope).toEqual({
+      kind: "authorization",
+      authorization: {
+        actorId: "actor-7",
+        scopeDigest: "sha256:scope-9",
+        generation: 4,
+      },
+    });
+  });
+
+  test("uses the transaction-bound append seam and keeps ids idempotent", async () => {
+    const ids: string[] = [];
+    const producer = authoritativeRegistry().bindInvalidationProducer({
+      moduleKey: "case.material",
+      append: {
+        async append(envelope) {
+          ids.push(envelope.invalidationId);
+          return ids.length === 1 ? "appended" : "duplicate";
+        },
+      },
+    });
+
+    await expect(producer.sourceDeleted(input(11))).resolves.toBe("appended");
+    await expect(producer.sourceDeleted(input(11))).resolves.toBe("duplicate");
+    expect(ids[0]).toBe(ids[1]);
+  });
+
+  test("fails closed without a registered authority or Host-bound grant", async () => {
+    const registry = authoritativeRegistry();
+    expect(() => registry.bindInvalidationProducer({
+      moduleKey: "unknown.module",
+      append: recordingAppend([]),
+    })).toThrow("权威来源 Adapter 未注册");
+
+    const producer = registry.bindInvalidationProducer({
+      moduleKey: "case.material",
+      append: recordingAppend([]),
+    });
+    await expect(producer.authorizationRevoked(input(15))).rejects.toBeInstanceOf(
+      ModuleAuthoritativeInvalidationUnavailableError,
+    );
+  });
+});
+
+function authoritativeRegistry() {
+  return new ModuleAuthoritativeSourceAccessRegistry([{
+    moduleKey: "case.material",
+    access: {
+      authorizeCurrent: async () => ({
+        outcome: "denied" as const,
+        reason: "object-forbidden" as const,
+      }),
+    },
+  }]);
+}
+
+function recordingAppend(appended: SourceInvalidationEnvelopeV1[]) {
+  return {
+    async append(
+      envelope: SourceInvalidationEnvelopeV1,
+    ): Promise<SourceInvalidationAppendResult> {
+      appended.push(envelope);
+      return "appended";
+    },
+  };
+}
+
+function input(sequence: number) {
+  return {
+    source: {
+      sourceKind: "evidence-file",
+      sourceId: "file-9",
+      version: `version-${sequence}`,
+      sequence,
+      digest: "a".repeat(64),
+    },
+    event: {
+      eventId: `event-${sequence}`,
+      eventSequence: sequence,
+      occurredAt: "2026-08-28T08:00:00.000Z",
+    },
+  };
+}