create-windy 0.6.12 → 0.6.15

package/template/apps/server/src/agent/session-context-source.ts

@@ -0,0 +1,346 @@
+import {
+  agentContextMessages,
+  agentContextVersions,
+  agentMemoryProjections,
+  agentSessionEvents,
+} from "@southwind-ai/database";
+import { and, eq } from "drizzle-orm";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
+import type { RequestGuardContext } from "../guards.js";
+import type {
+  ContextSourcePort,
+  ContextSourceRequest,
+  ResolvedContextSource,
+} from "./context-memory/contracts.js";
+import { stableDigest } from "./context-memory/digest.js";
+import {
+  memoryProjectionContent,
+  memoryProjectionScopeId,
+} from "./context-memory/memory-content.js";
+import type { MemoryProjection } from "./context-memory/contracts.js";
+import type { SessionId, SessionTurnId } from "./session-log/domain.js";
+import type {
+  AuthoritativeSourceAccessPort,
+  AuthoritativeSourceAccessQuery,
+} from "./session-invalidation/contracts.js";
+import type { DrizzleSessionEventRepository } from "./session-persistence/drizzle-session-repository.js";
+import { mapEvent } from "./session-persistence/drizzle-session-mapping.js";
+import type { AgentSessionPayloadCodec } from "./session-persistence/payload-codec.js";
+import type { AgentRuntimePort } from "./run-contracts.js";
+import { recoverContextMessage } from "./context-message-recovery.js";
+import {
+  requireContextSourceChain,
+  requireMemorySourceChain,
+} from "./session-source-chain-authorizer.js";
+import {
+  deniedSourceAccess as denied,
+  linkedRun,
+  sessionTurnContextContent,
+} from "./session-context-source-support.js";
+export { sessionTurnContextContent } from "./session-context-source-support.js";
+const MODULE_KEY = "system.agent";
+const SOURCE_KIND = "recent-event";
+export class SessionTurnContextSourcePort implements ContextSourcePort {
+  constructor(
+    private readonly repository: DrizzleSessionEventRepository,
+    private readonly sessionId: SessionId,
+    private readonly turnId: SessionTurnId,
+  ) {}
+  async resolve(
+    request: ContextSourceRequest,
+    context: RequestGuardContext,
+    _signal: AbortSignal,
+  ): Promise<ResolvedContextSource> {
+    if (
+      request.moduleKey !== MODULE_KEY ||
+      request.kind !== SOURCE_KIND ||
+      !request.id.trim()
+    ) {
+      throw new Error("Context 来源不受支持");
+    }
+    const session = await this.repository.get(this.sessionId);
+    const event = await this.repository.findEvent(this.sessionId, request.id);
+    if (
+      !session ||
+      session.status !== "active" ||
+      session.governance.actorId !== context.actor.id ||
+      !event ||
+      event.data.type !== "turn.started" ||
+      event.data.turnId !== this.turnId
+    ) {
+      throw new Error("Context 来源不存在或不可访问");
+    }
+    const content = sessionTurnContextContent(event);
+    return {
+      role: "user",
+      reference: {
+        moduleKey: MODULE_KEY,
+        kind: SOURCE_KIND,
+        id: event.eventId,
+        version: event.eventId,
+        sequence: event.sequence,
+        digest: stableDigest({ role: "user", content }),
+        validity: {
+          status: "valid",
+          checkedAt: event.occurredAt,
+        },
+      },
+      content,
+    };
+  }
+}
+/** Production authority for immutable system.agent Session Event sources. */
+export class DrizzleSessionAuthoritativeSourceAccess implements AuthoritativeSourceAccessPort {
+  #memorySources?: AuthoritativeSourceAccessPort;
+  constructor(
+    private readonly db: NodePgDatabase,
+    private readonly codec: AgentSessionPayloadCodec,
+    private readonly repository: DrizzleSessionEventRepository,
+    private readonly remote?: AgentRuntimePort,
+  ) {}
+  bindMemorySourceAuthority(authority: AuthoritativeSourceAccessPort) {
+    if (this.#memorySources) throw new Error("Memory 来源 Authority 已绑定");
+    this.#memorySources = authority;
+  }
+  async authorizeCurrent(query: AuthoritativeSourceAccessQuery) {
+    const source = query.source;
+    if (
+      source.moduleKey === MODULE_KEY &&
+      [
+        "working-context",
+        "system-instruction",
+        "operation-instruction",
+        "artifact-summary",
+      ].includes(source.sourceKind) &&
+      source.sourceId.startsWith("context_")
+    ) {
+      return this.authorizeStoredMessage(query);
+    }
+    if (
+      source.moduleKey === MODULE_KEY &&
+      [
+        "working-context",
+        "session-summary",
+        "user-preference",
+        "case-memory-candidate",
+        "verified-fact-reference",
+      ].includes(source.sourceKind)
+    ) {
+      return this.authorizeMemory(query);
+    }
+    if (source.moduleKey === MODULE_KEY && source.sourceKind === "run-result") {
+      return this.authorizeRunResult(query);
+    }
+    if (
+      source.moduleKey !== MODULE_KEY ||
+      source.sourceKind !== SOURCE_KIND ||
+      source.sourceId !== source.version
+    ) {
+      return denied();
+    }
+    const [row] = await this.db
+      .select()
+      .from(agentSessionEvents)
+      .where(eq(agentSessionEvents.eventId, source.sourceId))
+      .limit(1);
+    const event = row ? mapEvent(this.codec, row) : undefined;
+    if (!event || event.data.type !== "turn.started") return denied();
+    const session = await this.repository.get(event.sessionId);
+    const digest = stableDigest({
+      role: "user",
+      content: sessionTurnContextContent(event),
+    });
+    if (
+      !session ||
+      session.status !== "active" ||
+      session.governance.actorId !== query.authorization.actorId ||
+      session.governance.scopeDigest !== query.authorization.scopeDigest ||
+      event.sequence !== source.sequence ||
+      source.digest !== digest
+    ) {
+      return denied();
+    }
+    return {
+      outcome: "allowed" as const,
+      sourceVersion: event.eventId,
+      sourceSequence: event.sequence,
+      authorizationGeneration: query.authorization.generation,
+    };
+  }
+
+  private async authorizeStoredMessage(query: AuthoritativeSourceAccessQuery) {
+    const source = query.source;
+    const separator = source.sourceId.lastIndexOf(":");
+    const contextVersionId = source.sourceId.slice(0, separator);
+    const ordinal = Number(source.sourceId.slice(separator + 1));
+    if (
+      separator < 1 ||
+      source.version !== contextVersionId ||
+      !Number.isSafeInteger(ordinal) ||
+      ordinal < 0 ||
+      source.sequence !== ordinal + 1
+    )
+      return denied();
+    const [row] = await this.db
+      .select({
+        sessionId: agentContextVersions.sessionId,
+        status: agentContextVersions.status,
+        role: agentContextMessages.role,
+        contentCipher: agentContextMessages.contentCipher,
+        payloadDigest: agentContextMessages.payloadDigest,
+      })
+      .from(agentContextMessages)
+      .innerJoin(
+        agentContextVersions,
+        eq(
+          agentContextMessages.contextVersionId,
+          agentContextVersions.contextVersionId,
+        ),
+      )
+      .where(
+        and(
+          eq(agentContextMessages.contextVersionId, contextVersionId),
+          eq(agentContextMessages.ordinal, ordinal),
+        ),
+      )
+      .limit(1);
+    if (!row || row.status !== "active") return denied();
+    const session = await this.repository.get(row.sessionId as SessionId);
+    const content = this.codec.decode<ModuleAiJsonValue>(
+      row.contentCipher,
+      row.payloadDigest,
+    );
+    const recovered = recoverContextMessage(
+      row.role as "system" | "user" | "assistant" | "tool",
+      content,
+    );
+    if (
+      !session ||
+      session.status !== "active" ||
+      session.governance.actorId !== query.authorization.actorId ||
+      session.governance.scopeDigest !== query.authorization.scopeDigest ||
+      !source.digest ||
+      source.digest !== recovered.digest
+    )
+      return denied();
+    if (!this.#memorySources) return denied();
+    try {
+      await requireContextSourceChain(
+        this.db,
+        contextVersionId,
+        this.#memorySources,
+        query,
+      );
+    } catch {
+      return denied();
+    }
+    return {
+      outcome: "allowed" as const,
+      sourceVersion: contextVersionId,
+      sourceSequence: ordinal + 1,
+      authorizationGeneration: query.authorization.generation,
+    };
+  }
+
+  private async authorizeMemory(query: AuthoritativeSourceAccessQuery) {
+    const source = query.source;
+    const [row] = await this.db
+      .select()
+      .from(agentMemoryProjections)
+      .where(
+        and(
+          eq(agentMemoryProjections.memoryId, source.sourceId),
+          eq(agentMemoryProjections.status, "active"),
+        ),
+      )
+      .limit(1);
+    if (
+      !row ||
+      row.kind !== source.sourceKind ||
+      (row.expiresAt !== null && row.expiresAt <= Date.now())
+    )
+      return denied();
+    const projection = this.codec.decode<MemoryProjection>(
+      row.payloadCipher,
+      row.payloadDigest,
+    );
+    const session = await this.repository.get(
+      row.derivedFromSessionId as SessionId,
+    );
+    const content = memoryProjectionContent(projection);
+    if (
+      projection.version !== source.version ||
+      projection.kind !== row.kind ||
+      projection.scope.kind !== row.scopeKind ||
+      memoryProjectionScopeId(projection) !== row.scopeId ||
+      projection.currentCaseId !== (row.currentCaseId ?? undefined) ||
+      row.derivedThroughSequence !== source.sequence ||
+      source.digest !== stableDigest({ role: "system", content }) ||
+      !session ||
+      session.status !== "active" ||
+      session.governance.actorId !== query.authorization.actorId ||
+      session.governance.scopeDigest !== query.authorization.scopeDigest ||
+      (row.scopeKind === "user" &&
+        row.scopeId !== query.authorization.actorId) ||
+      (row.scopeKind === "session" &&
+        row.scopeId !== row.derivedFromSessionId) ||
+      projection.validity.status !== "valid"
+    )
+      return denied();
+    if (!this.#memorySources) return denied();
+    try {
+      await requireMemorySourceChain(
+        this.db,
+        row.memoryId,
+        this.#memorySources,
+        query,
+      );
+    } catch {
+      return denied();
+    }
+    return {
+      outcome: "allowed" as const,
+      sourceVersion: projection.version,
+      sourceSequence: row.derivedThroughSequence,
+      authorizationGeneration: query.authorization.generation,
+    };
+  }
+
+  private async authorizeRunResult(query: AuthoritativeSourceAccessQuery) {
+    if (!this.remote) return denied();
+    const source = query.source;
+    const separator = source.sourceId.indexOf("/");
+    const sessionId = source.sourceId.slice(0, separator) as SessionId;
+    const runId = source.sourceId.slice(separator + 1);
+    if (separator < 1 || !runId.trim()) return denied();
+    const session = await this.repository.get(sessionId);
+    if (
+      !session ||
+      session.status !== "active" ||
+      session.governance.actorId !== query.authorization.actorId ||
+      session.governance.scopeDigest !== query.authorization.scopeDigest ||
+      !(await linkedRun(this.repository, sessionId, runId))
+    )
+      return denied();
+    const status = await this.remote.status(runId);
+    if (
+      status.status !== "completed" ||
+      status.lastSequence !== source.sequence ||
+      source.version !== String(status.lastSequence)
+    )
+      return denied();
+    const response = await this.remote.result(runId);
+    if (!response.ok) return denied();
+    const content = JSON.stringify(await response.json());
+    if (source.digest !== stableDigest({ role: "assistant", content })) {
+      return denied();
+    }
+    return {
+      outcome: "allowed" as const,
+      sourceVersion: source.version,
+      sourceSequence: source.sequence,
+      authorizationGeneration: query.authorization.generation,
+    };
+  }
+}

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

@@ -0,0 +1,216 @@
+export const SOURCE_INVALIDATION_CONTRACT_VERSION = 1 as const;
+
+export const SOURCE_INVALIDATION_PROJECTION_TARGETS = [
+  "search",
+  "embedding",
+  "context",
+  "memory",
+  "ui",
+] as const;
+
+export type SourceInvalidationProjectionTarget =
+  (typeof SOURCE_INVALIDATION_PROJECTION_TARGETS)[number];
+
+export interface CausalSourceReference {
+  readonly moduleKey: string;
+  readonly sourceKind: string;
+  readonly sourceId: string;
+  readonly version: string;
+  readonly sequence: number;
+  readonly digest?: string;
+}
+
+interface SourceInvalidationEventCoordinate {
+  readonly eventId: string;
+  readonly eventSequence: number;
+}
+
+export type SourceInvalidationCausation =
+  | (SourceInvalidationEventCoordinate & {
+      readonly kind: "session-event";
+      readonly sessionId: string;
+    })
+  | (SourceInvalidationEventCoordinate & {
+      readonly kind: "domain-event" | "retention-policy";
+    })
+  | (SourceInvalidationEventCoordinate & {
+      readonly kind: "authoritative-source-lifecycle";
+      readonly authorityModuleKey: string;
+    });
+
+export type SourceInvalidationTransition =
+  | {
+      readonly reason: "authorization-revoked";
+      readonly targetState: "revoked";
+    }
+  | { readonly reason: "source-deleted"; readonly targetState: "deleted" }
+  | { readonly reason: "source-archived"; readonly targetState: "archived" }
+  | {
+      readonly reason:
+        | "source-invalidated"
+        | "source-expired"
+        | "source-superseded";
+      readonly targetState: "invalid";
+    };
+
+export interface SourceAuthorizationCoordinate {
+  readonly actorId: string;
+  readonly scopeDigest: string;
+  readonly generation: number;
+  /** Optional server-derived scope; authorities that need containment must require it. */
+  readonly scopeSnapshot?: import("@southwind-ai/shared").AuthorizationScopeSnapshot;
+}
+
+type SourceInvalidationEnvelopeBase = {
+  readonly contractVersion: typeof SOURCE_INVALIDATION_CONTRACT_VERSION;
+  readonly invalidationId: string;
+  readonly source: CausalSourceReference;
+  readonly occurredAt: string;
+};
+
+export type AuthoritativeSourceDeletionEnvelopeV1 =
+  SourceInvalidationEnvelopeBase & {
+    readonly causedBy: SourceInvalidationCausation & {
+      readonly kind: "authoritative-source-lifecycle";
+      readonly authorityModuleKey: string;
+    };
+    readonly transition: {
+      readonly reason: "source-deleted";
+      readonly targetState: "deleted";
+    };
+    readonly scope: { readonly kind: "resource" };
+  };
+
+/** Session 生命周期只收敛该 Session 的派生投影，不冒充业务来源生命周期。 */
+export type SessionDerivedInvalidationEnvelopeV1 =
+  SourceInvalidationEnvelopeBase & {
+    readonly source: CausalSourceReference & {
+      readonly moduleKey: "system.agent";
+      readonly sourceKind: "session";
+    };
+    readonly causedBy: SourceInvalidationCausation & {
+      readonly kind: "session-event";
+      readonly sessionId: string;
+    };
+    readonly transition: {
+      readonly reason: "source-archived";
+      readonly targetState: "archived";
+    };
+    readonly scope: {
+      readonly kind: "session-derived";
+      readonly sessionId: string;
+    };
+  };
+
+export type SourceInvalidationEnvelopeV1 =
+  | (SourceInvalidationEnvelopeBase & {
+      readonly causedBy: SourceInvalidationCausation;
+      readonly transition: {
+        readonly reason: "authorization-revoked";
+        readonly targetState: "revoked";
+      };
+      readonly scope: {
+        /** Sinks converge Session-derived projections for this Actor; source matching alone is insufficient. */
+        readonly kind: "authorization";
+        readonly authorization: SourceAuthorizationCoordinate;
+      };
+    })
+  | (SourceInvalidationEnvelopeBase & {
+      readonly causedBy: SourceInvalidationCausation;
+      readonly transition: Exclude<
+        SourceInvalidationTransition,
+        | { readonly reason: "authorization-revoked" }
+        | { readonly reason: "source-deleted" }
+      >;
+      readonly scope: { readonly kind: "resource" };
+    })
+  | AuthoritativeSourceDeletionEnvelopeV1
+  | SessionDerivedInvalidationEnvelopeV1;
+
+export interface SourceInvalidationDelivery {
+  readonly deliveryId: string;
+  readonly target: SourceInvalidationProjectionTarget;
+  readonly envelope: SourceInvalidationEnvelopeV1;
+  readonly attempt: number;
+  readonly leaseToken: string;
+}
+
+export type SourceInvalidationAppendResult = "appended" | "duplicate" | "stale";
+
+/**
+ * 由持久化 Adapter 将 append 与触发它的 Session/领域事实写入同一事务。
+ * 每个 Projection Target 独立 claim/complete，避免局部成功被误认为整体完成。
+ */
+export interface SessionSourceInvalidationOutboxPort {
+  append(
+    envelope: SourceInvalidationEnvelopeV1,
+  ): Promise<SourceInvalidationAppendResult>;
+  claim(input: {
+    readonly workerId: string;
+    readonly limit: number;
+    readonly leaseUntil: string;
+  }): Promise<readonly SourceInvalidationDelivery[]>;
+  complete(deliveryId: string, leaseToken: string): Promise<void>;
+  retry(input: {
+    readonly deliveryId: string;
+    readonly leaseToken: string;
+    readonly retryAt: string;
+    readonly errorCode: string;
+  }): Promise<void>;
+  reject(input: {
+    readonly deliveryId: string;
+    readonly leaseToken: string;
+    readonly errorCode: string;
+  }): Promise<void>;
+}
+
+export type SourceInvalidationProjectionResult =
+  | "applied"
+  | "duplicate"
+  | "stale";
+
+export interface SourceInvalidationProjectionPort<
+  TTarget extends SourceInvalidationProjectionTarget =
+    SourceInvalidationProjectionTarget,
+> {
+  readonly target: TTarget;
+  invalidate(input: {
+    readonly deliveryId: string;
+    readonly envelope: SourceInvalidationEnvelopeV1;
+  }): Promise<SourceInvalidationProjectionResult>;
+}
+
+export type SourceInvalidationProjectionPorts = {
+  readonly [TTarget in SourceInvalidationProjectionTarget]: SourceInvalidationProjectionPort<TTarget>;
+};
+
+export interface AuthoritativeSourceAccessQuery {
+  readonly source: CausalSourceReference;
+  readonly authorization: SourceAuthorizationCoordinate;
+  readonly requestId: string;
+}
+
+export type AuthoritativeSourceAccessDecision =
+  | {
+      readonly outcome: "allowed";
+      readonly sourceVersion: string;
+      readonly sourceSequence: number;
+      readonly authorizationGeneration: number;
+    }
+  | {
+      readonly outcome: "denied";
+      readonly reason:
+        | "authorization-revoked"
+        | "source-deleted"
+        | "source-archived"
+        | "source-invalid"
+        | "source-stale"
+        | "object-forbidden";
+    };
+
+/** 权威业务对象读取端；不得用 Search/Embedding/Context 投影实现。 */
+export interface AuthoritativeSourceAccessPort {
+  authorizeCurrent(
+    query: AuthoritativeSourceAccessQuery,
+  ): Promise<AuthoritativeSourceAccessDecision>;
+}