@remnic/core 9.30.0 → 9.31.0

package/src/access-observe-helpers.ts

@@ -0,0 +1,180 @@
+type PendingObservePreparation = {
+  cancelled: boolean;
+  scopeHint?: string;
+  principal?: string;
+  namespace?: string;
+  released: Promise<void>;
+  release: () => void;
+};
+
+export type PendingObservePreparationHandle = {
+  isCancelled(): boolean;
+  setScope(principal?: string, namespace?: string): void;
+  release(): void;
+};
+
+export function pendingObserveScopeHint(options: {
+  namespace?: string;
+  projectTag?: string;
+  cwd?: string;
+}): string | undefined {
+  const namespace = options.namespace?.trim();
+  if (namespace) return `namespace:${namespace}`;
+  const projectTag = options.projectTag?.trim();
+  if (projectTag) return `projectTag:${projectTag}`;
+  const cwd = options.cwd?.trim();
+  return cwd ? `cwd:${cwd}` : undefined;
+}
+
+type PendingObserveExtraction = {
+  promise: Promise<void>;
+  controllers: Set<AbortController>;
+};
+
+export class PendingObserveExtractionTracker {
+  private readonly entries = new Map<string, PendingObserveExtraction>();
+  private readonly preparations = new Map<string, Set<PendingObservePreparation>>();
+
+  reserve(sessionKey: string, scopeHint?: string): PendingObservePreparationHandle {
+    let released = false;
+    let resolveReleased: () => void = () => {};
+    const reservation: PendingObservePreparation = {
+      cancelled: false,
+      scopeHint,
+      released: new Promise<void>((resolve) => {
+        resolveReleased = resolve;
+      }),
+      release: () => {
+        if (released) return;
+        released = true;
+        const entries = this.preparations.get(sessionKey);
+        entries?.delete(reservation);
+        if (entries?.size === 0) this.preparations.delete(sessionKey);
+        resolveReleased();
+      },
+    };
+    const entries = this.preparations.get(sessionKey) ?? new Set<PendingObservePreparation>();
+    entries.add(reservation);
+    this.preparations.set(sessionKey, entries);
+    return {
+      isCancelled: () => reservation.cancelled,
+      setScope: (principal, namespace) => {
+        reservation.principal = principal;
+        reservation.namespace = namespace;
+      },
+      release: reservation.release,
+    };
+  }
+
+  private async waitForPreparations(sessionKey: string): Promise<void> {
+    while (true) {
+      const pending = [...(this.preparations.get(sessionKey) ?? [])].filter(
+        (reservation) => !reservation.cancelled,
+      );
+      if (pending.length === 0) return;
+      await Promise.all(pending.map((reservation) => reservation.released));
+    }
+  }
+
+
+  key(sessionKey: string, principal: string | undefined, namespace: string | undefined): string {
+    return `${sessionKey}\u0000${principal ?? ""}\u0000${namespace ?? ""}`;
+  }
+
+  track(key: string, extraction: Promise<void>, controller: AbortController): void {
+    const previous = this.entries.get(key);
+    const promise = previous
+      ? Promise.allSettled([previous.promise, extraction]).then((results) => {
+          const rejected = results.find((result): result is PromiseRejectedResult => result.status === "rejected");
+          if (rejected) throw rejected.reason;
+        })
+      : extraction;
+    const entry = {
+      promise,
+      controllers: new Set(previous ? [...previous.controllers, controller] : [controller]),
+    };
+    this.entries.set(key, entry);
+    void promise
+      .then(() => {
+        if (this.entries.get(key) === entry) this.entries.delete(key);
+      })
+      .catch(() => {
+        // Keep a failed barrier visible to the next lifecycle flush.
+      });
+  }
+
+  cancel(
+    sessionKey: string,
+    principal?: string,
+    namespace?: string,
+    scopeHint?: string,
+  ): void {
+    for (const reservation of this.preparations.get(sessionKey) ?? []) {
+      const principalMatches =
+        principal === undefined ||
+        reservation.principal === undefined ||
+        reservation.principal === principal;
+      const namespaceMatches =
+        namespace === undefined ||
+        reservation.namespace === undefined ||
+        reservation.namespace === namespace;
+      const resolvedScopeMatches =
+        namespace !== undefined &&
+        reservation.namespace === namespace &&
+        principalMatches;
+      const scopeHintMismatch =
+        (reservation.scopeHint !== undefined && reservation.scopeHint !== scopeHint) ||
+        (reservation.scopeHint === undefined && scopeHint !== undefined);
+      if ((!resolvedScopeMatches && scopeHintMismatch) || !principalMatches || !namespaceMatches) {
+        continue;
+      }
+      reservation.cancelled = true;
+    }
+
+    for (const [key, entry] of this.entries) {
+      const [entrySessionKey, entryPrincipal, entryNamespace] = key.split("\u0000");
+      if (
+        entrySessionKey !== sessionKey ||
+        (principal !== undefined && entryPrincipal !== (principal ?? "")) ||
+        (namespace !== undefined && entryNamespace !== (namespace ?? ""))
+      )
+        continue;
+      for (const controller of entry.controllers) controller.abort();
+    }
+  }
+
+  async wait(
+    sessionKey: string,
+    principal: string | undefined,
+    namespace: string | undefined,
+    abortSignal?: AbortSignal,
+    registerCancellation?: (cancel: () => void) => void,
+    scopeHint?: string,
+  ): Promise<void> {
+    const key = this.key(sessionKey, principal, namespace);
+    const abortTracked = (): void => {
+      this.cancel(sessionKey, principal, namespace, scopeHint);
+    };
+    registerCancellation?.(abortTracked);
+    abortSignal?.addEventListener("abort", abortTracked, { once: true });
+    try {
+      await this.waitForPreparations(sessionKey);
+      while (true) {
+        const entry = this.entries.get(key);
+        if (!entry) return;
+        try {
+          await entry.promise;
+        } catch (error) {
+          if (this.entries.get(key) !== entry) continue;
+          this.entries.delete(key);
+          throw error;
+        }
+        if (this.entries.get(key) !== entry) continue;
+        this.entries.delete(key);
+        return;
+      }
+    } finally {
+      abortSignal?.removeEventListener("abort", abortTracked);
+    }
+  }
+}

package/src/access-observe-write-surface.ts

@@ -11,7 +11,25 @@
  */
 
 import { createHash } from "node:crypto";
-import { buildAccessWriteRequestFingerprint } from "./write-envelope.js";
+import {
+  type CodingScopedWriteInput,
+  ENGRAM_ACCESS_WRITE_SCHEMA_VERSION,
+  type EngramAccessBriefingRequest,
+  type EngramAccessBriefingResponse,
+  type EngramAccessExtractionForceFlushRequest,
+  type EngramAccessExtractionForceFlushResponse,
+  EngramAccessInputError,
+  type EngramAccessMemoryStoreRequest,
+  type EngramAccessObserveRequest,
+  type EngramAccessObserveResponse,
+  type EngramAccessQmdCollectionState,
+  type EngramAccessQmdHealthResponse,
+  type EngramAccessSuggestionSubmitRequest,
+  type EngramAccessWriteResponse,
+  type MemoryScopePlan,
+  NamespaceNotWritableError,
+} from "./access-service.js";
+import { extractionForceFlush } from "./access-extraction-force-flush.js";
 import { FileCalendarSource, buildBriefing, parseBriefingFocus, parseBriefingWindow } from "./briefing.js";
 import {
   resolveCompressionCapabilities,
@@ -32,24 +50,9 @@ import type { MemoryActionOutcome, MemoryActionType } from "./types.js";
 import { exportWorkBoardMarkdown, exportWorkBoardSnapshot, importWorkBoardSnapshot } from "./work/board.js";
 import { wrapWorkLayerContext } from "./work/boundary.js";
 import { WorkStorage } from "./work/storage.js";
-import { WriteQuarantineStore, type QuarantineOperation } from "./write-quarantine.js";
-import {
-  ENGRAM_ACCESS_WRITE_SCHEMA_VERSION,
-  EngramAccessInputError,
-  NamespaceNotWritableError,
-  type CodingScopedWriteInput,
-  type EngramAccessBriefingRequest,
-  type EngramAccessBriefingResponse,
-  type EngramAccessMemoryStoreRequest,
-  type EngramAccessObserveRequest,
-  type EngramAccessObserveResponse,
-  type EngramAccessQmdCollectionState,
-  type EngramAccessQmdHealthResponse,
-  type EngramAccessSuggestionSubmitRequest,
-  type EngramAccessWriteResponse,
-  type MemoryScopePlan,
-} from "./access-service.js";
-
+import { buildAccessWriteRequestFingerprint } from "./write-envelope.js";
+import { type QuarantineOperation, WriteQuarantineStore } from "./write-quarantine.js";
+import { PendingObserveExtractionTracker, pendingObserveScopeHint } from "./access-observe-helpers.js";
 export interface AccessObserveWriteSurfaceDeps {
   attachCodingContextAfterScopedWrite(
     request: CodingScopedWriteInput & { namespace?: string; sessionKey?: string }
@@ -107,6 +110,12 @@ export interface AccessObserveWriteSurfaceDeps {
       authenticatedPrincipal?: string;
     }
   ): Promise<MemoryScopePlan>;
+  cancelPendingObserveExtractions?(
+    sessionKey: string,
+    principal?: string,
+    namespace?: string,
+    scopeHint?: string,
+  ): void;
   resolveReadableNamespace(namespace: string | undefined, principal?: string): string;
   validateWriteCandidate(
     request: EngramAccessMemoryStoreRequest | EngramAccessSuggestionSubmitRequest,
@@ -121,7 +130,16 @@ export interface AccessObserveWriteSurfaceDeps {
 
 export class AccessObserveWriteSurface {
   private quarantineStoreInstance?: WriteQuarantineStore;
+  private readonly pendingObserveExtractions = new PendingObserveExtractionTracker();
 
+  public cancelPendingObserveExtractions(
+    sessionKey: string,
+    principal?: string,
+    namespace?: string,
+    scopeHint?: string,
+  ): void {
+    this.pendingObserveExtractions.cancel(sessionKey, principal, namespace, scopeHint);
+  }
   constructor(private readonly deps: AccessObserveWriteSurfaceDeps) {}
 
   private quarantineStore(): WriteQuarantineStore {
@@ -654,6 +672,12 @@ export class AccessObserveWriteSurface {
     //    self base leaves NO coding context bound to the session, matching how
     //    `memory_store` resolves its full scoped write namespace before any
     //    session mutation.
+    const observePreparation = this.pendingObserveExtractions.reserve(
+      request.sessionKey,
+      pendingObserveScopeHint(request),
+    );
+    try {
+
     let scope: MemoryScopePlan;
     try {
       scope = await this.deps.resolveMemoryScopePlan(request);
@@ -666,6 +690,7 @@ export class AccessObserveWriteSurface {
       throw err;
     }
     const writeNamespace = scope.writeNamespace;
+    observePreparation.setScope(scope.principal, writeNamespace);
 
     // Backward-compatible BASE writable namespace (pre-#1495 response semantics)
     // for the legacy `namespace` response field. DERIVED from the already-resolved
@@ -812,21 +837,35 @@ export class AccessObserveWriteSurface {
       // limits concurrency (one extraction at a time per session via
       // queueBufferedExtraction). Fire-and-forget here just decouples
       // the HTTP response from the queue drain.
+      if (!observePreparation.isCancelled()) {
+
       try {
+        const observeAbortController = new AbortController();
         const extractionPromise = this.deps.orchestrator.ingestReplayBatch(turns, {
           archiveLcm: false,
           writeNamespaceOverride,
           principalOverride,
+          abortSignal: observeAbortController.signal,
+          ...(typeof request.authenticatedPrincipal === "string" && request.authenticatedPrincipal.trim().length > 0
+            ? { sessionOwnerPrincipal: request.authenticatedPrincipal.trim() }
+            : {}),
         });
         extractionPromise.catch((err) => {
           log.error(`access-observe background extraction failed: ${err}`);
         });
+        this.pendingObserveExtractions.track(
+          this.pendingObserveExtractions.key(request.sessionKey, scope.principal, writeNamespace),
+          extractionPromise,
+          observeAbortController,
+        );
         extractionQueued = true;
       } catch (err) {
         // Synchronous enqueue failure (e.g. orchestrator disposed)
         log.error(`access-observe extraction enqueue failed: ${err}`);
       }
     }
+      }
+
 
     log.info(
       `access-observe namespace=${namespace} effectiveNamespace=${writeNamespace} sessionKey=${request.sessionKey} messages=${request.messages.length} lcm=${lcmArchived} extraction=${extractionQueued}`
@@ -852,8 +891,28 @@ export class AccessObserveWriteSurface {
       lcmArchived,
       extractionQueued,
     };
+    } finally {
+      observePreparation.release();
+  }
   }
 
+  async extractionForceFlush(
+    request: EngramAccessExtractionForceFlushRequest,
+  ): Promise<EngramAccessExtractionForceFlushResponse> {
+    return extractionForceFlush(
+      this.deps,
+      request,
+      (sessionKey, principal, namespace, abortSignal, registerCancellation, scopeHint) =>
+        this.pendingObserveExtractions.wait(
+          sessionKey,
+          principal,
+          namespace,
+          abortSignal,
+          registerCancellation,
+          scopeHint,
+        ),
+    );
+  }
   async workTask(request: {
     action: "create" | "get" | "list" | "update" | "transition" | "delete";
     id?: string;

package/src/access-operations-batch.ts

@@ -194,7 +194,8 @@ defineOperation({ name: "observe", description: "Observe messages.", schema: str
   handler: async (input, ctx) => ({ result: await ctx.service.observe({ sessionKey: defStr(input.sessionKey, ""), messages: (input.messages as unknown[]).map((m: unknown) => { const r = m as Record<string, unknown>; return { role: String(r.role), content: String(r.content), parts: r.parts as unknown[], rawContent: r.rawContent as string | undefined, sourceFormat: r.sourceFormat as string | undefined }; }) as never, skipExtraction: input.skipExtraction === true, idempotencyKey: optStr(input.idempotencyKey), namespace: optStr(input.namespace), authenticatedPrincipal: ctx.authenticatedPrincipal, cwd: optStr(input.cwd), projectTag: optStr(input.projectTag), ...(ctx.sourceConnector ? { sourceConnector: ctx.sourceConnector } : {}) }, ctx.hooks?.enforceWriteQuota ? { enforceWriteQuota: ctx.hooks.enforceWriteQuota } : undefined) }),
 });
 defineOperation({ name: "lcm_search", description: "Search LCM.", schema: strictSchema({ query: S.str, sessionKey: S.str, sessionPrefix: S.str, namespace: S.str, limit: S.num }), handler: async (input, ctx) => ({ result: await ctx.service.lcmSearch({ query: defStr(input.query, ""), sessionKey: optStr(input.sessionKey), sessionPrefix: optStr(input.sessionPrefix), namespace: optStr(input.namespace), limit: optNum(input.limit), authenticatedPrincipal: ctx.authenticatedPrincipal }) }) });
-defineOperation({ name: "lcm_compaction_flush", description: "Flush LCM compaction.", schema: strictSchema({ sessionKey: S.str, namespace: S.str }), handler: async (input, ctx) => ({ result: await ctx.service.lcmCompactionFlush({ sessionKey: optStr(input.sessionKey) ?? "", namespace: optStr(input.namespace), authenticatedPrincipal: ctx.authenticatedPrincipal }) }) });
+defineOperation({ name: "lcm_compaction_flush", description: "Flush LCM compaction.", schema: strictSchema({ sessionKey: S.str, namespace: S.str, cwd: S.str, projectTag: S.str }), handler: async (input, ctx) => ({ result: await ctx.service.lcmCompactionFlush({ sessionKey: optStr(input.sessionKey) ?? "", namespace: optStr(input.namespace), cwd: optStr(input.cwd), projectTag: optStr(input.projectTag), authenticatedPrincipal: ctx.authenticatedPrincipal }) }) });
+defineOperation({ name: "extraction_force_flush", description: "Force-drain a session extraction buffer.", schema: strictSchema({ sessionKey: S.str, namespace: S.str, cwd: S.str, projectTag: S.str, deadlineMs: S.num }), handler: async (input, ctx) => ({ result: await ctx.service.extractionForceFlush({ sessionKey: optStr(input.sessionKey) ?? "", namespace: optStr(input.namespace), cwd: optStr(input.cwd), projectTag: optStr(input.projectTag), deadlineMs: optNum(input.deadlineMs), authenticatedPrincipal: ctx.authenticatedPrincipal, onCommitted: ctx.hooks?.recordWriteCommit, ...(ctx.abortSignal ? { abortSignal: ctx.abortSignal } : {}) }) }) });
 defineOperation({ name: "lcm_compaction_record", description: "Record LCM compaction.", schema: strictSchema({ sessionKey: S.str, namespace: S.str, tokensBefore: S.num, tokensAfter: S.num }), handler: async (input, ctx) => ({ result: await ctx.service.lcmCompactionRecord({ sessionKey: optStr(input.sessionKey) ?? "", namespace: optStr(input.namespace), tokensBefore: optNum(input.tokensBefore) ?? 0, tokensAfter: optNum(input.tokensAfter) ?? 0, authenticatedPrincipal: ctx.authenticatedPrincipal }) }) });
 
 // === CONTINUITY/IDENTITY ===

package/src/access-schema-pi.test.ts

@@ -58,6 +58,23 @@ test("LCM compaction flush rejects duplicate namespace batches", () => {
   assert.equal(result.success, false);
 });
 
+test("extraction force-flush schema accepts scoped deadlines and rejects invalid deadlines", () => {
+  const accepted = validateRequest("extractionForceFlush", {
+    sessionKey: "pi:session",
+    namespace: "work",
+    cwd: "/workspace/project",
+    projectTag: "Acme/Webshop",
+    deadlineMs: 1_900_000_000_000,
+  });
+  assert.equal(accepted.success, true);
+
+  const rejected = validateRequest("extractionForceFlush", {
+    sessionKey: "pi:session",
+    deadlineMs: -1,
+  });
+  assert.equal(rejected.success, false);
+});
+
 test("LCM compaction record rejects invalid token counts", () => {
   const result = validateRequest("lcmCompactionRecord", {
     sessionKey: "pi:session",

package/src/access-schema.ts

@@ -44,6 +44,14 @@ export function formatZodError(error: z.ZodError): SchemaValidationError {
 const namespaceSchema = z.string().trim().max(256).optional();
 const sessionKeySchema = z.string().trim().min(1).max(512).optional();
 const idempotencyKeySchema = z.string().trim().min(1).max(256).optional();
+const cwdSchema = z.string().trim().min(1, "cwd must be non-empty when provided").max(2048).optional();
+const projectTagSchema = z
+  .string()
+  .trim()
+  .min(1, "projectTag must be non-empty when provided")
+  .max(256)
+  .optional();
+const deadlineMsSchema = z.number().finite().min(0).max(Number.MAX_SAFE_INTEGER).optional();
 const dryRunSchema = z.boolean().optional();
 const schemaVersionSchema = z.number().int().optional();
 const timeZoneSchema = z
@@ -108,12 +116,12 @@ export const recallRequestSchema = z.object({
   disclosure: recallDisclosureSchema.optional(),
   codingContext: codingContextSchema.optional(),
   /** Working directory for auto git-context resolution (issue #569). */
-  cwd: z.string().trim().min(1, "cwd must be non-empty when provided").max(2048).optional(),
+  cwd: cwdSchema,
   /**
    * Arbitrary project tag for non-git-based project scoping (issue #569).
    * Creates a coding context with `projectId: "tag:<projectTag>"`.
    */
-  projectTag: z.string().trim().min(1, "projectTag must be non-empty when provided").max(256).optional(),
+  projectTag: projectTagSchema,
   /**
    * Historical recall pin (issue #680).  ISO 8601 timestamp.  The
    * schema only enforces the basic shape; the access service runs
@@ -225,12 +233,12 @@ export const observeRequestSchema = z.object({
    */
   idempotencyKey: idempotencyKeySchema,
   /** Working directory for auto git-context resolution (issue #569). */
-  cwd: z.string().trim().min(1, "cwd must be non-empty when provided").max(2048).optional(),
+  cwd: cwdSchema,
   /**
    * Arbitrary project tag for non-git-based project scoping (issue #569).
    * Creates a coding context with `projectId: "tag:<projectTag>"`.
    */
-  projectTag: z.string().trim().min(1, "projectTag must be non-empty when provided").max(256).optional(),
+  projectTag: projectTagSchema,
 });
 
 // ---------------------------------------------------------------------------
@@ -268,13 +276,8 @@ export const memoryStoreRequestSchema = z.object({
   // `namespace` is given, these route the write to the same project namespace
   // recall/observe resolve from `cwd`/`projectTag` (issue #569, rule 42). Also
   // lets MCP clients that auto-inject `cwd` (e.g. Pi MCPorter) call write tools.
-  cwd: z.string().trim().min(1, "cwd must be non-empty when provided").max(2048).optional(),
-  projectTag: z
-    .string()
-    .trim()
-    .min(1, "projectTag must be non-empty when provided")
-    .max(256)
-    .optional(),
+  cwd: cwdSchema,
+  projectTag: projectTagSchema,
 });
 
 export const suggestionSubmitRequestSchema = memoryStoreRequestSchema;
@@ -335,6 +338,8 @@ export const lcmCompactionFlushRequestSchema = z
   .object({
     sessionKey: z.string().trim().min(1, "sessionKey is required").max(512),
     namespace: namespaceSchema,
+    cwd: cwdSchema,
+    projectTag: projectTagSchema,
     /**
      * Optional multi-namespace flush used by delegate lifecycle replay. The
      * server handles the whole list as one quota-counted write.
@@ -361,6 +366,14 @@ export const lcmCompactionFlushRequestSchema = z
     }
   });
 
+export const extractionForceFlushRequestSchema = z.object({
+  sessionKey: z.string().trim().min(1, "sessionKey is required").max(512),
+  namespace: namespaceSchema,
+  cwd: cwdSchema,
+  projectTag: projectTagSchema,
+  deadlineMs: deadlineMsSchema,
+});
+
 export const lcmCompactionRecordRequestSchema = z.object({
   sessionKey: z.string().trim().min(1, "sessionKey is required").max(512),
   namespace: namespaceSchema,
@@ -583,6 +596,7 @@ export type TrustZonePromoteRequest = z.infer<typeof trustZonePromoteRequestSche
 export type TrustZoneDemoSeedRequest = z.infer<typeof trustZoneDemoSeedRequestSchema>;
 export type LcmSearchRequest = z.infer<typeof lcmSearchRequestSchema>;
 export type LcmCompactionFlushRequest = z.infer<typeof lcmCompactionFlushRequestSchema>;
+export type ExtractionForceFlushRequest = z.infer<typeof extractionForceFlushRequestSchema>;
 export type LcmCompactionRecordRequest = z.infer<typeof lcmCompactionRecordRequestSchema>;
 export type DaySummaryRequest = z.infer<typeof daySummaryRequestSchema>;
 export type CapsuleExportRequest = z.infer<typeof capsuleExportRequestSchema>;
@@ -610,6 +624,7 @@ export type SchemaName =
   | "trustZoneDemoSeed"
   | "lcmSearch"
   | "lcmCompactionFlush"
+  | "extractionForceFlush"
   | "lcmCompactionRecord"
   | "daySummary"
   | "capsuleExport"
@@ -633,6 +648,7 @@ export type SchemaTypeFor<N extends SchemaName> =
   : N extends "trustZoneDemoSeed" ? TrustZoneDemoSeedRequest
   : N extends "lcmSearch" ? LcmSearchRequest
   : N extends "lcmCompactionFlush" ? LcmCompactionFlushRequest
+  : N extends "extractionForceFlush" ? ExtractionForceFlushRequest
   : N extends "lcmCompactionRecord" ? LcmCompactionRecordRequest
   : N extends "daySummary" ? DaySummaryRequest
   : N extends "capsuleExport" ? CapsuleExportRequest
@@ -657,6 +673,7 @@ const schemas: Record<SchemaName, z.ZodTypeAny> = {
   trustZoneDemoSeed: trustZoneDemoSeedRequestSchema,
   lcmSearch: lcmSearchRequestSchema,
   lcmCompactionFlush: lcmCompactionFlushRequestSchema,
+  extractionForceFlush: extractionForceFlushRequestSchema,
   lcmCompactionRecord: lcmCompactionRecordRequestSchema,
   daySummary: daySummaryRequestSchema,
   capsuleExport: capsuleExportRequestSchema,

package/src/access-service-helpers.ts

@@ -0,0 +1,46 @@
+import type { CodingScopedWriteInput } from "./access-service.js";
+
+
+export interface EngramAccessLcmCompactionFlushRequest extends CodingScopedWriteInput {
+  sessionKey: string;
+  namespace?: string;
+  authenticatedPrincipal?: string;
+}
+
+export interface EngramAccessLcmCompactionFlushResponse {
+  enabled: boolean;
+  flushed: boolean;
+  sessionKey: string;
+  namespace: string;
+  reason?: string;
+}
+
+export interface EngramAccessExtractionForceFlushRequest extends CodingScopedWriteInput {
+  sessionKey: string;
+  namespace?: string;
+  authenticatedPrincipal?: string;
+  deadlineMs?: number;
+  abortSignal?: AbortSignal;
+  /** Internal HTTP hook invoked at the durable commit boundary. */
+  onCommitted?: () => void;
+}
+
+export interface EngramAccessExtractionForceFlushResponse {
+  flushed: boolean;
+  sessionKey: string;
+  namespace: string;
+  effectiveNamespace: string;
+}
+
+export interface ExtractionForceFlushDelegate {
+  extractionForceFlush(
+    request: EngramAccessExtractionForceFlushRequest,
+  ): Promise<EngramAccessExtractionForceFlushResponse>;
+}
+
+export function delegateExtractionForceFlush(
+  delegate: ExtractionForceFlushDelegate,
+  request: EngramAccessExtractionForceFlushRequest,
+): Promise<EngramAccessExtractionForceFlushResponse> {
+  return delegate.extractionForceFlush(request);
+}