create-windy 0.6.12 → 0.6.15

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

@@ -0,0 +1,202 @@
+import { createHash } from "node:crypto";
+import type {
+  CausalSourceReference,
+  SourceAuthorizationCoordinate,
+  SourceInvalidationAppendResult,
+  SourceInvalidationEnvelopeV1,
+} from "./contracts.js";
+import { assertSourceInvalidationEnvelope } from "./dispatcher.js";
+
+export interface TransactionalSourceInvalidationAppendPort {
+  /** The implementation must append through the caller's current business transaction. */
+  append(
+    envelope: SourceInvalidationEnvelopeV1,
+  ): Promise<SourceInvalidationAppendResult>;
+}
+
+export interface ModuleAuthoritativeSourceCoordinate {
+  readonly sourceKind: string;
+  readonly sourceId: string;
+  readonly version: string;
+  readonly sequence: number;
+  readonly digest?: string;
+}
+
+export interface ModuleAuthoritativeInvalidationEvent {
+  readonly eventId: string;
+  readonly eventSequence: number;
+  readonly occurredAt: string;
+}
+
+export interface ModuleAuthoritativeInvalidationInput {
+  readonly source: ModuleAuthoritativeSourceCoordinate;
+  readonly event: ModuleAuthoritativeInvalidationEvent;
+}
+
+/** Business callers receive this bound port and never supply module or authorization identity. */
+export interface ModuleAuthoritativeInvalidationProducerPort {
+  sourceDeleted(
+    input: ModuleAuthoritativeInvalidationInput,
+  ): Promise<SourceInvalidationAppendResult>;
+  sourceExpired(
+    input: ModuleAuthoritativeInvalidationInput,
+  ): Promise<SourceInvalidationAppendResult>;
+  sourceSuperseded(
+    input: ModuleAuthoritativeInvalidationInput,
+  ): Promise<SourceInvalidationAppendResult>;
+  authorizationRevoked(
+    input: ModuleAuthoritativeInvalidationInput,
+  ): Promise<SourceInvalidationAppendResult>;
+}
+
+export interface ModuleAuthoritativeInvalidationHostBinding {
+  readonly moduleKey: string;
+  readonly append: TransactionalSourceInvalidationAppendPort;
+  /** Host-captured coordinate of the grant being revoked; never accepted per call. */
+  readonly authorization?: SourceAuthorizationCoordinate;
+}
+
+export class ModuleAuthoritativeInvalidationUnavailableError extends Error {
+  readonly code = "SOURCE_INVALIDATION_UNAVAILABLE" as const;
+
+  constructor() {
+    super("权威来源失效写入暂不可用");
+    this.name = "ModuleAuthoritativeInvalidationUnavailableError";
+  }
+}
+
+export function createModuleAuthoritativeInvalidationProducer(
+  binding: ModuleAuthoritativeInvalidationHostBinding,
+): ModuleAuthoritativeInvalidationProducerPort {
+  const moduleKey = binding.moduleKey.trim();
+  if (
+    !moduleKey ||
+    (binding.authorization && !validAuthorization(binding.authorization))
+  ) {
+    throw unavailable();
+  }
+  const appendLifecycle = (
+    reason: "source-deleted" | "source-expired" | "source-superseded",
+    input: ModuleAuthoritativeInvalidationInput,
+  ) => append(binding.append, lifecycleEnvelope(moduleKey, reason, input));
+  return {
+    sourceDeleted: (input) => appendLifecycle("source-deleted", input),
+    sourceExpired: (input) => appendLifecycle("source-expired", input),
+    sourceSuperseded: (input) => appendLifecycle("source-superseded", input),
+    authorizationRevoked: async (input) => {
+      if (!binding.authorization) throw unavailable();
+      return append(
+        binding.append,
+        revocationEnvelope(moduleKey, binding.authorization, input),
+      );
+    },
+  };
+}
+
+function lifecycleEnvelope(
+  moduleKey: string,
+  reason: "source-deleted" | "source-expired" | "source-superseded",
+  input: ModuleAuthoritativeInvalidationInput,
+): SourceInvalidationEnvelopeV1 {
+  const source = sourceReference(moduleKey, input.source);
+  const base = {
+    contractVersion: 1 as const,
+    invalidationId: invalidationId(moduleKey, reason, input),
+    source,
+    causedBy: {
+      kind: "authoritative-source-lifecycle" as const,
+      authorityModuleKey: moduleKey,
+      eventId: input.event.eventId,
+      eventSequence: input.event.eventSequence,
+    },
+    occurredAt: input.event.occurredAt,
+    scope: { kind: "resource" as const },
+  };
+  if (reason === "source-deleted") {
+    return { ...base, transition: { reason, targetState: "deleted" } };
+  }
+  return { ...base, transition: { reason, targetState: "invalid" } };
+}
+
+function revocationEnvelope(
+  moduleKey: string,
+  authorization: SourceAuthorizationCoordinate,
+  input: ModuleAuthoritativeInvalidationInput,
+): SourceInvalidationEnvelopeV1 {
+  return {
+    contractVersion: 1,
+    invalidationId: invalidationId(
+      moduleKey,
+      "authorization-revoked",
+      input,
+      authorization,
+    ),
+    source: sourceReference(moduleKey, input.source),
+    causedBy: {
+      kind: "domain-event",
+      eventId: input.event.eventId,
+      eventSequence: input.event.eventSequence,
+    },
+    occurredAt: input.event.occurredAt,
+    transition: { reason: "authorization-revoked", targetState: "revoked" },
+    scope: { kind: "authorization", authorization },
+  };
+}
+
+async function append(
+  port: TransactionalSourceInvalidationAppendPort,
+  envelope: SourceInvalidationEnvelopeV1,
+) {
+  assertSourceInvalidationEnvelope(envelope);
+  return port.append(envelope);
+}
+
+function sourceReference(
+  moduleKey: string,
+  source: ModuleAuthoritativeSourceCoordinate,
+): CausalSourceReference {
+  return {
+    moduleKey,
+    sourceKind: source.sourceKind,
+    sourceId: source.sourceId,
+    version: source.version,
+    sequence: source.sequence,
+    ...(source.digest ? { digest: source.digest } : {}),
+  };
+}
+
+function invalidationId(
+  moduleKey: string,
+  reason: string,
+  input: ModuleAuthoritativeInvalidationInput,
+  authorization?: SourceAuthorizationCoordinate,
+) {
+  const digest = createHash("sha256").update(JSON.stringify([
+    moduleKey,
+    input.source.sourceKind,
+    input.source.sourceId,
+    input.source.version,
+    input.source.sequence,
+    input.source.digest ?? "",
+    reason,
+    input.event.eventId,
+    input.event.eventSequence,
+    authorization?.actorId ?? "",
+    authorization?.scopeDigest ?? "",
+    authorization?.generation ?? 0,
+  ])).digest("hex");
+  return `source_invalidation_${digest}`;
+}
+
+function validAuthorization(value: SourceAuthorizationCoordinate) {
+  return Boolean(
+    value.actorId.trim() &&
+      value.scopeDigest.trim() &&
+      Number.isSafeInteger(value.generation) &&
+      value.generation > 0,
+  );
+}
+
+function unavailable() {
+  return new ModuleAuthoritativeInvalidationUnavailableError();
+}

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

@@ -0,0 +1,39 @@
+import type {
+  AuthoritativeSourceAccessDecision,
+  AuthoritativeSourceAccessPort,
+  AuthoritativeSourceAccessQuery,
+} from "./contracts.js";
+
+export class SourceReadDeniedError extends Error {
+  readonly code = "SOURCE_ACCESS_DENIED" as const;
+
+  constructor() {
+    super("来源不存在或不可访问");
+    this.name = "SourceReadDeniedError";
+  }
+}
+
+/**
+ * 每次读取都查询权威业务对象。投影尚未消费撤权事件时，这里仍会立即拒绝。
+ * Port 超时、异常、版本漂移或授权 generation 漂移均按不可访问处理。
+ */
+export async function requireAuthoritativeSourceRead(
+  port: AuthoritativeSourceAccessPort,
+  query: AuthoritativeSourceAccessQuery,
+): Promise<Extract<AuthoritativeSourceAccessDecision, { outcome: "allowed" }>> {
+  let decision: AuthoritativeSourceAccessDecision;
+  try {
+    decision = await port.authorizeCurrent(query);
+  } catch {
+    throw new SourceReadDeniedError();
+  }
+  if (
+    decision.outcome !== "allowed" ||
+    decision.sourceVersion !== query.source.version ||
+    decision.sourceSequence !== query.source.sequence ||
+    decision.authorizationGeneration !== query.authorization.generation
+  ) {
+    throw new SourceReadDeniedError();
+  }
+  return decision;
+}

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

@@ -0,0 +1,69 @@
+import { randomUUID } from "node:crypto";
+import type {
+  SourceInvalidationProjectionPort,
+  SourceInvalidationProjectionTarget,
+} from "./contracts.js";
+import { SourceInvalidationDispatcher } from "./dispatcher.js";
+import { SourceInvalidationWorker } from "./worker.js";
+import type { DrizzleSessionInvalidationOutbox } from "../session-persistence/drizzle-invalidation-outbox.js";
+import type {
+  ExternalSourceInvalidationPort,
+  DrizzleMemoryInvalidationProjection,
+} from "../session-persistence/invalidation-projections.js";
+
+/** Search and Embedding share the canonical Memory projection in AH-1. */
+export class CanonicalMemoryIndexInvalidationPort
+  implements ExternalSourceInvalidationPort
+{
+  constructor(
+    private readonly memory: DrizzleMemoryInvalidationProjection,
+  ) {}
+
+  invalidate(input: Parameters<ExternalSourceInvalidationPort["invalidate"]>[0]) {
+    return this.memory.invalidate(input);
+  }
+}
+
+export class SourceInvalidationScheduler {
+  readonly #workerId = `agent-source-invalidation-${randomUUID()}`;
+  readonly #timer: ReturnType<typeof setInterval>;
+  #running = false;
+
+  constructor(
+    outbox: DrizzleSessionInvalidationOutbox,
+    ports: {
+      readonly [T in SourceInvalidationProjectionTarget]:
+        SourceInvalidationProjectionPort<T>;
+    },
+    intervalMs = 2_000,
+  ) {
+    const worker = new SourceInvalidationWorker(
+      outbox,
+      new SourceInvalidationDispatcher(ports),
+    );
+    const run = async () => {
+      if (this.#running) return;
+      this.#running = true;
+      const now = Date.now();
+      try {
+        await worker.runOnce({
+          workerId: this.#workerId,
+          limit: 50,
+          leaseUntil: new Date(now + 30_000).toISOString(),
+          retryAt: new Date(now + 30_000).toISOString(),
+        });
+      } catch {
+        // Delivery rows remain pending/leased and become claimable after the lease.
+      } finally {
+        this.#running = false;
+      }
+    };
+    this.#timer = setInterval(() => void run(), intervalMs);
+    this.#timer.unref?.();
+    queueMicrotask(() => void run());
+  }
+
+  dispose() {
+    clearInterval(this.#timer);
+  }
+}

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

@@ -0,0 +1,24 @@
+import type { SourceInvalidationEnvelopeV1 } from "./contracts.js";
+
+export function sessionArchiveInvalidation(): SourceInvalidationEnvelopeV1 {
+  return {
+    contractVersion: 1,
+    invalidationId: "invalidate-session-12",
+    source: {
+      moduleKey: "system.agent",
+      sourceKind: "session",
+      sourceId: "session-1",
+      version: "12",
+      sequence: 12,
+    },
+    causedBy: {
+      kind: "session-event",
+      eventId: "session-event-12",
+      eventSequence: 12,
+      sessionId: "session-1",
+    },
+    occurredAt: "2026-08-27T08:00:00.000Z",
+    transition: { reason: "source-archived", targetState: "archived" },
+    scope: { kind: "session-derived", sessionId: "session-1" },
+  };
+}

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

@@ -0,0 +1,135 @@
+import { describe, expect, test } from "bun:test";
+import {
+  SOURCE_INVALIDATION_PROJECTION_TARGETS,
+  type SessionSourceInvalidationOutboxPort,
+  type SourceInvalidationDelivery,
+  type SourceInvalidationEnvelopeV1,
+  type SourceInvalidationProjectionPorts,
+} from "./contracts.js";
+import {
+  SourceInvalidationDispatcher,
+  sourceInvalidationDeliveryId,
+} from "./dispatcher.js";
+import { SourceInvalidationWorker } from "./worker.js";
+
+describe("SourceInvalidationWorker contract", () => {
+  test("completes convergence, retries target failure and rejects bad protocol", async () => {
+    const envelope = invalidation();
+    const deliveries = [
+      delivery(envelope, "context"),
+      delivery(envelope, "embedding"),
+      {
+        ...delivery(envelope, "search"),
+        deliveryId: "forged-delivery-id",
+      },
+    ] as const;
+    const outbox = new RecordingOutbox(deliveries);
+    const dispatcher = new SourceInvalidationDispatcher(
+      projectionPorts("embedding"),
+    );
+    const worker = new SourceInvalidationWorker(outbox, dispatcher);
+
+    await expect(
+      worker.runOnce({
+        workerId: "worker-1",
+        limit: 10,
+        leaseUntil: "2026-08-27T08:01:00.000Z",
+        retryAt: "2026-08-27T08:02:00.000Z",
+      }),
+    ).resolves.toEqual({
+      claimed: 3,
+      completed: { applied: 1, duplicate: 0, stale: 0 },
+      retried: 1,
+      rejected: 1,
+    });
+    expect(outbox.completed).toEqual(["invalidate-11:context"]);
+    expect(outbox.retried).toEqual(["invalidate-11:embedding"]);
+    expect(outbox.rejected).toEqual(["forged-delivery-id"]);
+  });
+});
+
+class RecordingOutbox implements SessionSourceInvalidationOutboxPort {
+  readonly completed: string[] = [];
+  readonly retried: string[] = [];
+  readonly rejected: string[] = [];
+
+  constructor(
+    private readonly deliveries: readonly SourceInvalidationDelivery[],
+  ) {}
+
+  async append() {
+    return "appended" as const;
+  }
+
+  async claim() {
+    return this.deliveries;
+  }
+
+  async complete(deliveryId: string) {
+    this.completed.push(deliveryId);
+  }
+
+  async retry(input: { readonly deliveryId: string }) {
+    this.retried.push(input.deliveryId);
+  }
+
+  async reject(input: { readonly deliveryId: string }) {
+    this.rejected.push(input.deliveryId);
+  }
+}
+
+function projectionPorts(
+  failing: "embedding" | undefined,
+): SourceInvalidationProjectionPorts {
+  return Object.fromEntries(
+    SOURCE_INVALIDATION_PROJECTION_TARGETS.map((target) => [
+      target,
+      {
+        target,
+        invalidate: async () => {
+          if (target === failing) throw new Error("projection unavailable");
+          return "applied" as const;
+        },
+      },
+    ]),
+  ) as unknown as SourceInvalidationProjectionPorts;
+}
+
+function delivery(
+  envelope: SourceInvalidationEnvelopeV1,
+  target: SourceInvalidationDelivery["target"],
+): SourceInvalidationDelivery {
+  return {
+    deliveryId: sourceInvalidationDeliveryId(
+      envelope.invalidationId,
+      target,
+    ),
+    target,
+    envelope,
+    attempt: 1,
+    leaseToken: `lease-${target}`,
+  };
+}
+
+function invalidation(): SourceInvalidationEnvelopeV1 {
+  return {
+    contractVersion: 1,
+    invalidationId: "invalidate-11",
+    source: {
+      moduleKey: "analysis",
+      sourceKind: "evidence-file",
+      sourceId: "file-9",
+      version: "source-v4",
+      sequence: 11,
+    },
+    transition: { reason: "source-deleted", targetState: "deleted" },
+    scope: { kind: "resource" },
+    causedBy: {
+      kind: "authoritative-source-lifecycle",
+      authorityModuleKey: "analysis",
+      eventId: "event-11",
+      eventSequence: 11,
+    },
+    occurredAt: "2026-08-27T08:00:00.000Z",
+  };
+}

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

@@ -0,0 +1,76 @@
+import type {
+  SessionSourceInvalidationOutboxPort,
+  SourceInvalidationProjectionResult,
+} from "./contracts.js";
+import {
+  SourceInvalidationDispatcher,
+  SourceInvalidationProtocolError,
+} from "./dispatcher.js";
+
+export interface SourceInvalidationWorkerResult {
+  readonly claimed: number;
+  readonly completed: Readonly<
+    Record<SourceInvalidationProjectionResult, number>
+  >;
+  readonly retried: number;
+  readonly rejected: number;
+}
+
+export class SourceInvalidationWorker {
+  constructor(
+    private readonly outbox: SessionSourceInvalidationOutboxPort,
+    private readonly dispatcher: SourceInvalidationDispatcher,
+  ) {}
+
+  async runOnce(input: {
+    readonly workerId: string;
+    readonly limit: number;
+    readonly leaseUntil: string;
+    readonly retryAt: string;
+  }): Promise<SourceInvalidationWorkerResult> {
+    const deliveries = await this.outbox.claim({
+      workerId: input.workerId,
+      limit: input.limit,
+      leaseUntil: input.leaseUntil,
+    });
+    const completed: Record<SourceInvalidationProjectionResult, number> = {
+      applied: 0,
+      duplicate: 0,
+      stale: 0,
+    };
+    let retried = 0;
+    let rejected = 0;
+    for (const delivery of deliveries) {
+      let result: SourceInvalidationProjectionResult;
+      try {
+        result = await this.dispatcher.dispatch(delivery);
+      } catch (error) {
+        if (error instanceof SourceInvalidationProtocolError) {
+          await this.outbox.reject({
+            deliveryId: delivery.deliveryId,
+            leaseToken: delivery.leaseToken,
+            errorCode: "INVALID_SOURCE_INVALIDATION_ENVELOPE",
+          });
+          rejected += 1;
+        } else {
+          await this.outbox.retry({
+            deliveryId: delivery.deliveryId,
+            leaseToken: delivery.leaseToken,
+            retryAt: input.retryAt,
+            errorCode: "SOURCE_INVALIDATION_TARGET_UNAVAILABLE",
+          });
+          retried += 1;
+        }
+        continue;
+      }
+      await this.outbox.complete(delivery.deliveryId, delivery.leaseToken);
+      completed[result] += 1;
+    }
+    return {
+      claimed: deliveries.length,
+      completed,
+      retried,
+      rejected,
+    };
+  }
+}

package/template/apps/server/src/agent/session-log/checkpoint-digest.ts

@@ -0,0 +1,36 @@
+import { createHash } from "node:crypto";
+import {
+  SessionDomainError,
+  type SessionCheckpoint,
+  type Sha256Digest,
+} from "./domain.js";
+import type { SessionEventEnvelope } from "./events.js";
+
+export function digestSessionFacts(
+  events: readonly SessionEventEnvelope[],
+): Sha256Digest {
+  return `sha256:${createHash("sha256")
+    .update(canonicalJson(events))
+    .digest("hex")}`;
+}
+
+export function assertCheckpointDigest(
+  checkpoint: SessionCheckpoint,
+  events: readonly SessionEventEnvelope[],
+): void {
+  if (
+    events.at(-1)?.sequence !== checkpoint.throughSequence ||
+    digestSessionFacts(events) !== checkpoint.factDigest
+  ) throw new SessionDomainError("Checkpoint fact digest 校验失败");
+}
+
+function canonicalJson(value: unknown): string {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value) ?? "null";
+  }
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  return `{${Object.entries(value)
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([key, child]) => `${JSON.stringify(key)}:${canonicalJson(child)}`)
+    .join(",")}}`;
+}

package/template/apps/server/src/agent/session-log/domain.ts

@@ -0,0 +1,123 @@
+import { randomUUID } from "node:crypto";
+
+export type SessionId = `session_${string}`;
+export type SessionEventId = `session_event_${string}`;
+export type SessionTurnId = `session_turn_${string}`;
+export type SessionStepId = `session_step_${string}`;
+export type SessionCheckpointId = `session_checkpoint_${string}`;
+
+export type Sha256Digest = `sha256:${string}`;
+
+export interface SessionGovernanceBinding {
+  readonly actorId: string;
+  readonly scopeDigest: Sha256Digest;
+}
+
+export interface SessionLineage {
+  readonly parentSessionId: SessionId;
+  readonly checkpointId: SessionCheckpointId;
+  readonly parentSequence: number;
+}
+
+export interface SessionRecord {
+  readonly sessionId: SessionId;
+  readonly governance: SessionGovernanceBinding;
+  readonly status: "active" | "archived";
+  readonly headSequence: number;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+  readonly lineage?: SessionLineage;
+}
+
+export interface SessionCheckpoint {
+  readonly checkpointId: SessionCheckpointId;
+  readonly sessionId: SessionId;
+  /** Last fact covered by this anchor. The checkpoint event follows it. */
+  readonly throughSequence: number;
+  readonly factDigest: Sha256Digest;
+  readonly createdAt: string;
+}
+
+export interface SessionIdentityFactory {
+  sessionId(): SessionId;
+  eventId(): SessionEventId;
+  turnId(): SessionTurnId;
+  stepId(): SessionStepId;
+  checkpointId(): SessionCheckpointId;
+}
+
+export function createSessionIdentityFactory(
+  uuid: () => string = randomUUID,
+): SessionIdentityFactory {
+  return {
+    sessionId: () => `session_${uuid()}`,
+    eventId: () => `session_event_${uuid()}`,
+    turnId: () => `session_turn_${uuid()}`,
+    stepId: () => `session_step_${uuid()}`,
+    checkpointId: () => `session_checkpoint_${uuid()}`,
+  };
+}
+
+export function assertSessionRecord(record: SessionRecord): void {
+  assertId(record.sessionId, "session_", "Session");
+  assertGovernance(record.governance);
+  assertSequence(record.headSequence, true);
+  assertTimestamp(record.createdAt, "Session createdAt");
+  assertTimestamp(record.updatedAt, "Session updatedAt");
+  if (record.lineage) {
+    assertId(record.lineage.parentSessionId, "session_", "父 Session");
+    assertId(
+      record.lineage.checkpointId,
+      "session_checkpoint_",
+      "Checkpoint",
+    );
+    assertSequence(record.lineage.parentSequence);
+    if (record.lineage.parentSessionId === record.sessionId) {
+      throw new SessionDomainError("Session 不能从自身派生");
+    }
+  }
+}
+
+export function assertGovernance(binding: SessionGovernanceBinding): void {
+  if (!binding.actorId.trim()) throw new SessionDomainError("Actor ID 不能为空");
+  assertDigest(binding.scopeDigest, "Scope digest");
+}
+
+export function assertDigest(
+  value: string,
+  label: string,
+): asserts value is Sha256Digest {
+  if (!/^sha256:[a-f0-9]{64}$/.test(value)) {
+    throw new SessionDomainError(`${label} 必须是 SHA-256 digest`);
+  }
+}
+
+export function assertId(
+  value: string,
+  prefix: string,
+  label: string,
+): void {
+  if (!value.startsWith(prefix) || value.length <= prefix.length) {
+    throw new SessionDomainError(`${label} ID 无效`);
+  }
+}
+
+export function assertSequence(value: number, allowZero = false): void {
+  const minimum = allowZero ? 0 : 1;
+  if (!Number.isSafeInteger(value) || value < minimum) {
+    throw new SessionDomainError("Session sequence 无效");
+  }
+}
+
+export function assertTimestamp(value: string, label: string): void {
+  if (!value || !Number.isFinite(Date.parse(value))) {
+    throw new SessionDomainError(`${label} 无效`);
+  }
+}
+
+export class SessionDomainError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "SessionDomainError";
+  }
+}