Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
import { isConnectorSourceKind } from './connector-identity.ts';
import type { BrainEngine, NewFact } from '../engine.ts';
import type { GBrainConfig } from '../config.ts';
import type { FactsBackstopCtx } from '../facts/backstop.ts';
import { factEventTime } from '../facts/event-time.ts';
import { ENTITY_HINTS_CAP, type ExtractedFact, type FactEmbeddingSignature } from '../facts/extract.ts';
import { readFactsEmbeddingDim } from '../embedding-dim-check.ts';
import { currentEmbeddingSignature } from '../embedding.ts';
import type { OperationContext } from '../ops/contract.ts';
import { OperationError, opError } from '../ops/contract.ts';
import { hostFix, opTransport, readFix } from '../ops/op-fix.ts';
import type { Action } from '../agent-output.ts';
import { resolveEntitySlugWithSource } from '../entities/resolve.ts';
import { appendContextNote, type InferredVia } from '../facts/subject-infer.ts';
import { inferenceNote } from '../facts/subject-infer-write.ts';
import { resolveDefaultVisibility } from '../facts/visibility.ts';
import { FACT_WITHDRAWN_MESSAGE, withdrawnFromDetail } from '../facts/withdrawal.ts';
import { currentSubmissionAuthority } from '../minions/submission-authority.ts';
import { loadActivePackForEngine } from '../schema-pack/engine-resolution.ts';
import { authorizeStoredRequest, authorizeWrite, submissionAuthority } from './authority.ts';
import { authorizePageVisibility } from './page-visibility.ts';
import { initializeLocalPersistence } from './page-mutations.ts';
import { prepareFileTarget } from './page-prepare.ts';
import { currentVerifiedLocalWriter, hostIdFor } from './identity.ts';
import { getWorktreeBinding, managedPersistenceEnabled, probeWorktreeWriter, type WorktreeBinding } from './ownership.ts';
import { authorizeFactsBackstop } from './effect-facts.ts';
import { admitWriteInTransaction, getWriteRequest, getWriteRequestById, receiptFor } from './journal.ts';
import { assertPersistenceAccepting, awaitWrite, persistenceConsumerConfig, writeResponse } from './service.ts';
import { MaintenanceWriteWait } from './maintenance-wait.ts';
import { CONSUMER_LIVE_MS } from './consumer-heartbeat.ts';
import { digest, requireUuid, sha256 } from './digest.ts';
import { isTerminal, type WriteAuthority, type WriteRequest } from './model.ts';
import type { WriteReceipt } from './types.ts';
import { FACTS_BATCH_INCOMPLETE_MESSAGE, isEntityMovedRefusal } from './verb-errors.ts';
import { assertAmbientCaptureAdmissible, captureGateLaneForSource } from '../facts/capture-sources.ts';
import { declareDerivation, type DerivationDeclaration } from '../trust/taint.ts';
import type { TaintInput, WriteTrust } from '../trust/tier.ts';
import { withSpeakerNote } from '../facts/speaker-context.ts';
export interface ManagedFactsResult {
inserted: number; duplicate: number; superseded: number; fact_ids: number[]; entity_slugs: string[]; write_requests: WriteReceipt[];
/** #6506: candidates the automatic extraction skipped because the exact claim was forgotten in this source and visibility. */
withdrawn_skipped?: number;
/** #6333 shadow: same-page rewordings the managed preparer counted; nothing was dropped. */
would_dedup_same_page?: number;
/** GBRA-130 A-36: entity requests that ended refused for their own page; the other entities' facts committed. */
refused?: ManagedFactsRefusal[];
}
export interface ManagedFactsRefusal { slug: string; code: string; request_id: string }
export interface ManagedFactOrigin { slug: string; pageId: number; revision: string; }
export type FrozenExtractedFact = Omit<NewFact, 'embedding' | 'valid_from' | 'valid_until' | 'expired_at'> & {
embedding: number[] | null; valid_from: string; valid_until: string | null;
/** #5836: a write-time inferred subject dedups exact text only, never superseding or dropping a similar fact. */
entity_inferred?: InferredVia;
};
export interface ManagedFactIntent extends Record<string, unknown> {
kind: 'managed_facts_entity' | 'managed_facts_complete';
batchKey: string; inputDigest: string; origin: ManagedFactOrigin | null; originalRequestId: string | null;
expected_revision?: string; facts?: FrozenExtractedFact[]; children?: string[];
/** Direct single-fact writes keep writeSingleFact's supersession rule. */
supersede?: true;
/**
* #6506: automatic extraction only. A candidate whose exact claim was forgotten in this source and visibility is
* skipped and counted (`withdrawn_skipped`) instead of refusing the entity's whole group; a purge tombstone still
* refuses. Explicit writers (remember, the fence writers) never set it and keep the refusal. Frozen in the stored
* intent, so a replay and a resumed batch decide exactly as the admission did.
*/
withdrawn?: 'skip';
/**
* writeSingleFact only: a `memory/unattributed` row keeps the resolver's
* fallback slug as its entity (no row number), so dedup stays per entity.
*/
attribute_fallback?: true;
embedding?: FactEmbeddingSignature | null;
/** #6091: the ambient capture lane (`hook:*`, `sweep:*`) the facts came from; admission re-checks its gate. */
capture_source?: string;
/** #5575 I2: the extraction's taint, declared at prompt-build time (trust/taint.ts). */
derivation?: DerivationDeclaration;
/**
* #6898 follow-up: set when the entity's facts were split into parts of at most
* MANAGED_FACTS_PUBLICATION_MAX facts, each its own request and publication. `deferred_facts` counts
* the facts left to later parts and `follow_up` names their request ids; both are copied into the
* part's receipt, so a part never reads as the whole group (the batch's completion request does).
*/
part?: ManagedFactsPart;
}
export interface ManagedFactsPart { index: number; of: number; deferred_facts: number; follow_up: string[] }
export interface ManagedFactsSession {
authority: WriteAuthority; binding: WorktreeBinding | null; config: GBrainConfig;
batchKey: string; inputDigest: string; origin: ManagedFactOrigin | null; originalRequestId: string | null;
completionRequestId: string;
embedding?: FactEmbeddingSignature | null;
/** #6048: the batch is keyed by its input alone and the caller asked to re-admit facts the canonical file check refused. */
fileRefusalRetry?: boolean;
/** #6506: the batch is keyed by its input alone (no request id), so a stored withdrawal refusal would replay on every run. */
inputKeyed?: boolean;
/**
* #7602: automatic extraction with no caller request id re-admits an entity request refused because its entity page
* moved, at the page's current revision. Explicit fact writers (remember, the fence writers) leave it unset and keep the refusal.
*/
entityMoveRetry?: boolean;
/** #6091: set when the facts come from an ambient capture lane. */
captureSource?: string;
/**
* GBRA-130 A-36: automatic extraction reports an entity refused for its own page under `refused` instead of throwing,
* so a replay returns the committed entities' counts. Explicit fact writers leave it unset and keep the refusal.
*/
reportRefusals?: boolean;
derivation?: DerivationDeclaration;
/**
* #6778: the publish wait, one budget per session: 30 s bounded by the job's deadline
* (FactsBackstopCtx.deadlineAtMs), zero for later publishes once one is still pending.
*/
wait: MaintenanceWriteWait;
/** The job's abort signal: a cancelled job stops waiting at once and its write stays pending. */
signal?: AbortSignal;
}
/** #6048: follow-up batches one extraction may admit for each followed refusal walk (file check, withdrawal, #7602 moved entity). */
export const MAX_FILE_REFUSAL_RETRIES = 3;
/**
* #6898 follow-up: the most facts one entity request publishes. A publication holds the brain-wide
* persistence_counters row from its admission check to its commit, and each fact adds a dedup check and
* an index insert to that window (measured ~3.5 ms per fact on Postgres; 200 facts on a 1.6 MB entity page
* held it 1.2 s, past the 1 s lock_timeout every other admission waits under). A larger group is admitted
* as parts in the same batch, published one after another in queue order.
*/
export const MANAGED_FACTS_PUBLICATION_MAX = 50;
const receiptFix = (requestId: string): Action => readFix('Reads the fact request\'s durable receipt: its operation, state and outcome, read-only.',
{ argv: ['gbrain', 'write-request', '--', requestId], mcp: { tool: 'get_write_request', arguments: { request_id: requestId } } });
const pageFix = (sourceId: string, slug: string): Action => readFix(`Shows page ${slug} in source ${sourceId} as it is now, with its revision.`,
{ argv: ['gbrain', 'get', '--source', sourceId, '--', slug], mcp: { tool: 'get_page', arguments: { slug, source_id: sourceId } } });
const ownerStatusFix = (sourceId: string): Action => readFix(`Shows source ${sourceId}'s canonical owner, its state and any write in flight, read-only.`,
{ argv: ['gbrain', 'sources', 'writer', 'status', '--source', sourceId, '--json'] });
const embeddingsFix = (): Action => readFix('Reports the brain\'s embedding model, dimensions and vector columns, read-only.',
{ argv: ['gbrain', 'doctor', '--only', 'embeddings', '--json'] });
function managedFactRequestId(batchKey: string, slug: string, part = 1): string {
const hex = digest(part === 1 ? [batchKey, slug] : [batchKey, slug, part]);
return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-8${hex.slice(13, 16)}-a${hex.slice(17, 20)}-${hex.slice(20, 32)}`;
}
async function validateManagedFactsCompletion(engine: BrainEngine, session: ManagedFactsSession, prior: WriteRequest): Promise<void> {
await authorizeStoredRequest(engine, prior);
const inputDigest = prior.intent?.inputDigest ?? prior.outcome?.input_digest;
if (prior.operation !== 'extract_facts' || prior.slug !== '__managed_facts_complete__'
|| prior.source_id !== session.authority.sourceId || prior.source_incarnation !== session.authority.sourceIncarnation
|| inputDigest !== undefined && inputDigest !== session.inputDigest) {
throw opError('idempotency_conflict', 'This request ID already belongs to another operation or extraction input.',
`Request ${prior.request_id} was already accepted for a different operation or extraction input, so nothing was admitted. Give this extraction a new request_id; read the receipt to see what the original request did.`,
{ fix: receiptFix(prior.request_id) });
}
if (prior.compacted && !prior.intent && isTerminal(prior) && prior.state !== 'committed') {
const error = new OperationError('facts_payload_expired', 'The accepted fact extraction failed and its retained payload has expired.',
'Inspect the original receipt. Any new extraction requires separate approval and a new request identity.');
error.writeRequest = receiptFor(prior);
throw error;
}
if (inputDigest !== session.inputDigest) throw opError('idempotency_conflict', 'The retained fact request cannot verify this extraction input.',
`Request ${prior.request_id} no longer retains the input digest needed to prove it matches this extraction, so nothing was admitted. Read its receipt; a new extraction needs a new request_id.`,
{ fix: receiptFix(prior.request_id) });
}
export async function resolveManagedFactsEmbedding(engine: BrainEngine, config: GBrainConfig,
lock = false): Promise<FactEmbeddingSignature | null> {
const rows = await engine.executeRaw<{ key: string; value: string }>(`SELECT key,value FROM config
WHERE key IN ('embedding_model','embedding_dimensions','embedding_disabled') ORDER BY key${lock ? ' FOR SHARE' : ''}`);
const values = Object.fromEntries(rows.map(row => [row.key, row.value]));
if (values.embedding_disabled !== undefined && values.embedding_disabled !== 'true' && values.embedding_disabled !== 'false') {
throw opError('embedding_configuration', 'Selected brain embedding_disabled must be true or false.',
'The brain\'s embedding_disabled setting is neither true nor false, so fact extraction stopped before admission. Read it, then have the user set it to true or false with gbrain config set embedding_disabled.',
{ fix: readFix('Shows the stored embedding_disabled value and the plane it comes from, read-only.', { argv: ['gbrain', 'config', 'get', 'embedding_disabled'] }) });
}
if (config.embedding_disabled || values.embedding_disabled === 'true') return null;
const model = values.embedding_model;
if (!model) return null;
const dimensions = /^[1-9]\d*$/.test(values.embedding_dimensions ?? '') ? Number(values.embedding_dimensions) : null;
if (!/[:/]/.test(model) && /^[^\s]+$/.test(model) && dimensions) {
// #6113: a legacy row stores the model without its provider. Name the one supported rewrite (a preview first).
const signature = currentEmbeddingSignature();
const gateway = signature ? signature.slice(0, signature.lastIndexOf(':')) : null;
const target = gateway?.endsWith(`:${model}`) ? gateway : null;
throw opError('embedding_configuration', 'The selected brain records its embedding model without a provider, so facts cannot be embedded.',
`The brain's embedding_model row is ${JSON.stringify(model)} with no provider prefix (a row from an older install), so fact extraction stopped before admission; gbrain config set cannot change it. `
+ `Preview the supported rewrite with gbrain migrate embeddings --to ${target ?? `<provider>:${model}`} --dry-run and show the user its cost: it re-embeds active facts, so applying it needs the user's paid authorization.`,
{ fix: target ? readFix(`Previews rewriting the brain's embedding identity to ${target}, read-only.`, { argv: ['gbrain', 'migrate', 'embeddings', '--to', target, '--dry-run'] }) : embeddingsFix() });
}
if (!/^[^\s:]+:[^\s]+$/.test(model) || !dimensions || !Number.isSafeInteger(dimensions)) {
throw opError('embedding_configuration', 'The selected brain has no verifiable facts embedding model and dimensions.',
`The brain's embedding_model (${JSON.stringify(model)}) is not provider:model or embedding_dimensions is not a positive integer, so fact extraction stopped before admission. Check embedding readiness; correcting the configuration is the user's decision.`,
{ fix: embeddingsFix() });
}
const shape = await readFactsEmbeddingDim(engine);
if (!shape.exists || !shape.columnType || shape.dims !== dimensions) {
throw opError('embedding_configuration', 'The selected brain facts embedding provenance does not match its vector column.',
`The facts vector column ${shape.exists ? `holds ${shape.dims ?? 'unknown'}-dimension vectors` : 'is missing'}, but ${model} is configured for ${dimensions}, so fact extraction stopped before admission. Check embedding readiness and show the user the mismatch.`,
{ fix: embeddingsFix() });
}
return { model, dimensions };
}
export async function assertManagedFactsEmbedding(engine: BrainEngine, config: GBrainConfig,
expected: FactEmbeddingSignature | null | undefined, lock = false): Promise<void> {
const current = await resolveManagedFactsEmbedding(engine, config, lock);
if (!expected || !current || expected.model !== current.model || expected.dimensions !== current.dimensions) {
throw opError('embedding_configuration', 'The selected brain facts embedding policy or model changed; retained vectors cannot be installed.',
`The facts embedding changed from ${expected ? `${expected.model} (${expected.dimensions})` : 'none'} to ${current ? `${current.model} (${current.dimensions})` : 'none'} after the facts were embedded, so nothing was admitted. Run the extraction again (the same request_id is safe: nothing was accepted) to embed under the current model.`,
{ fix: embeddingsFix() });
}
}
export async function prepareManagedFactsSession(ctx: FactsBackstopCtx,
input: { turnText: string; pageSlug?: string }, derivation?: { trust: WriteTrust; inputs: readonly TaintInput[] }): Promise<ManagedFactsSession | null> {
const engine = ctx.engine;
if (!(await managedPersistenceEnabled(engine))) return null;
assertPersistenceAccepting(engine);
const [source] = await engine.executeRaw<{ incarnation: string; archived: boolean; local_path: string | null; kind: string | null }>(
"SELECT incarnation,archived,local_path,config->>'kind' AS kind FROM sources WHERE id=$1", [ctx.sourceId]);
if (!source || source.archived) throw opError('source_changed', 'The fact extraction source is unavailable.',
`Source ${ctx.sourceId} is missing or archived, so no facts were extracted. Extract into an active source, or restore ${ctx.sourceId} first (the user's decision).`,
{ fix: readFix('Lists the registered sources with their archived state, read-only.', { argv: ['gbrain', 'sources', 'list', '--json'] }) });
let authority: WriteAuthority;
let origin: ManagedFactOrigin | null = null;
if (ctx.persistenceRequestId) {
const original = await getWriteRequestById(engine, requireUuid(ctx.persistenceRequestId));
if (!original || original.state !== 'committed' || original.source_id !== ctx.sourceId || original.source_incarnation !== source.incarnation || original.slug !== input.pageSlug) {
throw opError('permission_denied', 'Fact extraction requires its original committed page authority.',
`The page write that triggered fact extraction for ${input.pageSlug ?? 'this turn'} in source ${ctx.sourceId} is not a committed write of that page, so nothing was extracted. Read the write's receipt; facts are extracted only after it commits.`,
original ? { fix: receiptFix(original.request_id) } : {});
}
await authorizeFactsBackstop(engine, original);
authority = structuredClone(original.authority);
} else {
let operation = ctx.operationContext;
if (!operation) {
const verified = currentVerifiedLocalWriter();
const job = currentSubmissionAuthority();
if (job && job.kind !== 'application' || ctx.remote !== false && !verified && job?.kind !== 'application') {
throw opError('writer_coordinator_required', 'Managed facts require the original operation or durable job authority before extraction.',
`Fact extraction for source ${ctx.sourceId} ran outside an operation or durable job, so it has no authority to publish; nothing was extracted. Submit it as the extract_facts operation (an MCP tool call, or gbrain call extract_facts on the brain host).`);
}
operation = { engine, remote: verified?.remote ?? false, sourceId: ctx.sourceId, config: { engine: engine.kind } } as OperationContext;
}
if (operation.engine !== engine || operation.sourceId && operation.sourceId !== ctx.sourceId) throw opError('permission_denied', 'The extraction context does not match its source.',
`The calling operation targets ${operation.sourceId ? `source ${operation.sourceId}` : 'another brain'}, but extraction was asked to write into source ${ctx.sourceId}; nothing was extracted. Run the extraction with the same source as its operation.`);
await initializeLocalPersistence(operation);
authority = await submissionAuthority(operation, 'extract_facts', ctx.sourceId, source.incarnation, input.pageSlug ?? 'memory/unattributed');
}
if (authority.slugPrefixes !== null || authority.restrictedNamespace || authority.delegated) {
throw opError('permission_denied', 'Multi-entity fact extraction requires an unconfined source grant.',
`This writer's grant on source ${ctx.sourceId} is limited to slug prefixes, a restricted namespace or a delegation, so it cannot write facts across entities; nothing was extracted. Save a single fact inside the grant with remember, or ask the brain host's operator for a source-wide grant.`,
{ fix: ctx.operationContext
? hostFix(ctx.operationContext, opTransport(ctx.operationContext) === 'http' ? ['gbrain', 'auth', 'clients', '--json'] : ['gbrain', 'auth', 'local-writer', 'list', '--json'],
'Shows the connection\'s current grant so the operator can decide whether to widen it to the whole source.')
: readFix('Shows the CLI writer registrations and their grants, read-only.', { argv: ['gbrain', 'auth', 'local-writer', 'list', '--json'] }) });
}
await authorizeWrite(engine, authority, 'extract_facts', input.pageSlug ?? 'memory/unattributed');
for (const hint of ctx.entityHints?.slice(0, ENTITY_HINTS_CAP) ?? []) {
const resolved = await resolveEntitySlugWithSource(engine, ctx.sourceId, hint);
if (resolved && resolved.source !== 'fallback_slugify') {
await authorizeWrite(engine, authority, 'extract_facts', resolved.slug);
await authorizePageVisibility(engine, authority, resolved.slug);
}
}
if (input.pageSlug) {
await authorizePageVisibility(engine, authority, input.pageSlug);
const snapshot = await engine.readPageSnapshot(input.pageSlug, { sourceId: ctx.sourceId });
if (!snapshot || snapshot.sourceIncarnation !== source.incarnation || snapshot.page.compiled_truth !== input.turnText) {
throw opError('revision_conflict', 'The source page changed before fact extraction.',
`Page ${input.pageSlug} in source ${ctx.sourceId} no longer holds the text being extracted, so nothing was extracted. Read the current page and extract from its current text.`,
{ fix: pageFix(ctx.sourceId, input.pageSlug) });
}
origin = { slug: input.pageSlug, pageId: snapshot.page.id, revision: snapshot.revision };
if (ctx.persistenceRequestId) {
const original = (await getWriteRequestById(engine, ctx.persistenceRequestId))!;
if (original.outcome?.revision !== snapshot.revision) throw opError('revision_conflict', 'The original page write has been superseded.',
`A newer write replaced page ${input.pageSlug} in source ${ctx.sourceId} after request ${original.request_id} committed, so facts are not extracted from the superseded revision. Nothing needs resubmitting: the newer revision's write runs its own extraction.`,
{ fix: pageFix(ctx.sourceId, input.pageSlug) });
}
}
const binding = await getWorktreeBinding(engine, ctx.sourceId);
const root = source.local_path || (ctx.sourceId === 'default' ? await engine.getConfig('sync.repo_path') : null);
const writeThrough = !/^(false|0|off|no)$/i.test(await engine.getConfig('sync.write_through') ?? 'true');
// An unbound connector source is database-only by design (connector_database), like its connector sync.
const connectorDatabase = writeThrough && !binding && isConnectorSourceKind(source.kind);
if (writeThrough && root && !binding && !connectorDatabase) throw opError('owner_unavailable', 'The fact source has no canonical owner; extraction has not started.',
`Source ${ctx.sourceId} has a checkout but no canonical owner, so facts cannot be written through to it. Check writer status; claiming the checkout is the user's decision on the brain host.`,
{ fix: ownerStatusFix(ctx.sourceId) });
if (writeThrough && binding) {
if (binding.state !== 'active' || !binding.owner_host_id) throw opError('owner_unavailable', 'The canonical fact writer is unavailable; extraction has not started.',
`Source ${ctx.sourceId}'s canonical worktree is ${binding.state}, not active, so facts cannot be published yet. Check writer status and extract again once the owner is active.`,
{ fix: ownerStatusFix(ctx.sourceId) });
if (binding.owner_host_id === hostIdFor(engine)) {
if (!await probeWorktreeWriter(binding, engine)) throw opError('writer_lock_unavailable', 'The canonical fact writer is busy; extraction has not started.',
`Another write holds source ${ctx.sourceId}'s canonical writer. Nothing was admitted, so run the extraction again once the writer is idle (the same request_id is safe).`,
{ fix: ownerStatusFix(ctx.sourceId) });
}
}
if (!writeThrough) authority.databaseOnlyReason = 'disabled_by_config';
else if (connectorDatabase) authority.databaseOnlyReason = 'connector_database';
else if (!binding) authority.databaseOnlyReason = 'no_repo_configured';
const inputDigest = digest(ctx.requestIntent ?? { text: sha256(input.turnText), source: ctx.source, sessionId: ctx.sessionId, entityHints: ctx.entityHints ?? [],
visibility: ctx.visibility ?? null, validFrom: ctx.validFrom?.toISOString() ?? null, sourceSlug: ctx.sourceSlug ?? null,
model: ctx.model ?? null, filter: ctx.notabilityFilter ?? 'all' });
const seed = ctx.persistenceRequestId ?? (ctx.requestId ? requireUuid(ctx.requestId) : inputDigest);
const batchKey = digest(['managed-facts-v1', authority.principal, source.incarnation, seed]);
// With no caller config, admit under the config this process's consumer prepares with, so the embedding signature
// checked at admission is the one checked at preparation (a keyless consumer never receives embedded facts).
const config = ctx.operationContext?.config ?? ctx.config ?? persistenceConsumerConfig(engine) ?? { engine: engine.kind } as GBrainConfig;
const session: ManagedFactsSession = { authority, binding: writeThrough ? binding : null, config,
batchKey, inputDigest, origin, originalRequestId: ctx.persistenceRequestId ?? null,
completionRequestId: ctx.requestId ? requireUuid(ctx.requestId) : managedFactRequestId(batchKey, '__managed_facts_complete__'),
// #7439: a page-triggered job keeps its write's batch identity on retry, so its retained file refusal is
// rechecked once the hold clears instead of replayed forever. #7402: a caller's explicit request_id keeps
// returning its own recorded outcome, so it never rechecks.
fileRefusalRetry: !ctx.requestId && (!!ctx.persistenceRequestId || ctx.reAdmitFileRefusals === true && seed === inputDigest),
inputKeyed: seed === inputDigest,
wait: new MaintenanceWriteWait(ctx.deadlineAtMs ?? null), ...(ctx.abortSignal ? { signal: ctx.abortSignal } : {}),
...(captureGateLaneForSource(ctx.source) ? { captureSource: ctx.source } : {}),
...(derivation ? { derivation: declareDerivation(derivation.trust, derivation.inputs) } : {}) };
const prior = await getWriteRequest(engine, authority.principal, session.completionRequestId);
if (prior) await validateManagedFactsCompletion(engine, session, prior);
return session;
}
/**
* GBRA-130 A-36: codes one entity request ends on for reasons of its own page (changed, segmented, fence or content
* refused). Automatic extraction reports them under `refused` and keeps the committed entities' counts. A file-check
* refusal (`source_changed`) and a withdrawal refusal are not among them: they keep the batch refused, so the
* follow-up walks (#6048, #6506) re-admit their retained facts once the cause clears. An automatic extraction follows a
* `revision_conflict` whose entity page moved (#7602, followEntityMoves) before it reports it.
*/
const ENTITY_REFUSAL_CODES: ReadonlySet<string> = new Set(['revision_conflict', 'invalid_fence', 'target_fence_malformed', 'page_body_segmented',
'invalid_params', 'page_identity_changed', 'page_not_found', 'request_too_large', 'payload_too_large']);
/**
* Every row is awaited and collected before anything throws. A refused entity (ENTITY_REFUSAL_CODES) is reported when
* the session asks for it and another entity committed, and the completion receipt that only says the batch is
* incomplete is not a failure of its own; any other terminal row, then a still-pending one, then a refusal with
* nothing committed beside it, throws as its receipt.
*/
async function collectManagedFacts(engine: BrainEngine, session: ManagedFactsSession, rows: WriteRequest[]): Promise<ManagedFactsResult> {
const result: ManagedFactsResult = { inserted: 0, duplicate: 0, superseded: 0, fact_ids: [], entity_slugs: [], write_requests: [] };
const refused: WriteRequest[] = [];
let pending: WriteRequest | null = null;
let failed: WriteRequest | null = null;
let committed = 0;
for (const row of rows) {
if ((row.intent?.inputDigest ?? row.outcome?.input_digest) !== session.inputDigest) throw opError('idempotency_conflict', 'The fact request ID was already used with different extraction input.',
`Request ${row.request_id} in source ${row.source_id} was accepted for different extraction input, so this extraction was not merged into it. Give this extraction a new request_id; read the receipt to see the original.`,
{ fix: receiptFix(row.request_id) });
await authorizeStoredRequest(engine, row);
const finished = session.wait.observe((await awaitWrite(engine, row, session.config, { waitMs: session.wait.ms(), signal: session.signal })).row);
result.write_requests.push(receiptFor(finished));
if (finished.state !== 'committed') {
if (!isTerminal(finished)) pending ??= finished;
else if (isEntityRequest(finished) && ENTITY_REFUSAL_CODES.has(finished.error_code ?? '') && !withdrawalRefusal(finished)) refused.push(finished);
else if (isEntityRequest(finished) || !refused.length || finished.error_message !== FACTS_BATCH_INCOMPLETE_MESSAGE) failed ??= finished;
continue;
}
if (isEntityRequest(row)) {
committed++;
const out = finished.outcome!;
result.inserted += Number(out.inserted ?? 0);
result.duplicate += Number(out.duplicate ?? 0);
result.superseded += Number(out.superseded ?? 0);
result.fact_ids.push(...(out.fact_ids as number[] ?? []));
if (out.withdrawn_skipped) result.withdrawn_skipped = (result.withdrawn_skipped ?? 0) + Number(out.withdrawn_skipped);
if (out.would_dedup_same_page) result.would_dedup_same_page = (result.would_dedup_same_page ?? 0) + Number(out.would_dedup_same_page);
if (out.inserted && out.fenced && !result.entity_slugs.includes(row.slug)) result.entity_slugs.push(row.slug);
}
}
for (const row of [failed, pending]) if (row) writeResponse(row);
// #7602: the refusal stands after every follow-up walk, so a retry replays the same stored receipt.
if (refused.length && !(session.reportRefusals && committed)) {
try {
writeResponse(refused[0]);
} catch (error) {
if (error instanceof OperationError) error.retryable = false;
throw error;
}
}
if (refused.length) result.refused = refused.map(row => ({ slug: row.slug, code: row.error_code!, request_id: row.request_id }));
return result;
}
export async function resumeManagedFacts(engine: BrainEngine, session: ManagedFactsSession): Promise<ManagedFactsResult | null> {
const stored = await storedBatch(engine, session);
if (!stored) return null;
const files = session.fileRefusalRetry ? await followFileRefusals(engine, session, stored) : stored;
const embedded = session.fileRefusalRetry || session.inputKeyed ? await followEmbeddingRefusals(engine, session, files) : files;
const rows = session.inputKeyed ? await followWithdrawalRefusals(engine, session, embedded) : embedded;
return collectManagedFacts(engine, session, session.entityMoveRetry ? await followEntityMoves(engine, session, rows) : rows);
}
/** Every request journaled under the session's batch key, once its completion receipt validates; null when nothing was accepted. */
async function storedBatch(engine: BrainEngine, session: ManagedFactsSession): Promise<WriteRequest[] | null> {
const rows = await engine.executeRaw<WriteRequest>(`SELECT * FROM persistence_requests WHERE operation='extract_facts'
AND source_id=$1 AND source_incarnation=$2::uuid AND principal_kind=$3 AND principal_id=$4
AND (request_id=$6::uuid OR COALESCE(intent->>'batchKey',outcome->>'batch_key')=$5) ORDER BY sequence`, [session.authority.sourceId, session.authority.sourceIncarnation,
session.authority.principal.kind, session.authority.principal.id, session.batchKey, session.completionRequestId]);
if (!rows.length) return null;
const completion = rows.find(row => row.request_id === session.completionRequestId);
if (!completion) throw opError('storage_error', 'The accepted facts batch has no completion receipt.',
`Facts batch requests were accepted in source ${session.authority.sourceId} but their completion request ${session.completionRequestId} was never journaled, so the outcome is unconfirmed. Inspect accepted request ${rows[0].request_id} before resubmitting anything.`,
{ fix: receiptFix(rows[0].request_id) });
await validateManagedFactsCompletion(engine, session, completion);
return rows;
}
const isEntityRequest = (row: WriteRequest) => (row.intent?.kind ?? row.outcome?.kind) === 'managed_facts_entity';
/**
* #6048, #7439: an input-keyed batch (the sweep has no request id to give a window)
* and a page-triggered job's batch (keyed by its write) would replay a terminal
* file-check refusal forever. Walk the follow-up
* batches instead: while every request of the latest one is terminal and each
* uncommitted entity request is a `source_changed` refusal that kept its facts,
* look for the next follow-up, or admit it when every refused page now passes
* the file check. Returns the committed entity requests of earlier batches and
* all requests of the latest one, for collectManagedFacts to report.
*/
async function followFileRefusals(engine: BrainEngine, session: ManagedFactsSession, stored: WriteRequest[]): Promise<WriteRequest[]> {
return followRefusals(engine, session, stored, 'file-refusal-retry', row => row.error_code === 'source_changed', readmitRefusedFacts);
}
/**
* #8526: the same walk for a batch the write owner's consumer refused `embedding_configuration`, typically because it ran
* with a stale embedding config. The worker cannot see that consumer's config, so a follow-up is admitted only once no
* full consumer that was already running at the refusal is still live (the owner host's, or any when the rows have no
* worktree); until then the stored refusal replays and no follow-up is spent. The retained facts re-enter as #7602's do (readmitMovedFacts: current revision,
* retained visibility, an unattributed group kept, a deleted or replaced entity left refused), and admission rechecks the
* retained signature against the brain's current config, so after a real model change nothing is admitted. No
* extraction runs again.
*/
async function followEmbeddingRefusals(engine: BrainEngine, session: ManagedFactsSession, stored: WriteRequest[]): Promise<WriteRequest[]> {
return followRefusals(engine, session, stored, 'embedding-retry', row => row.error_code === 'embedding_configuration',
async (tx, followUp, refused) => await ownerRestartedSince(tx, refused) ? readmitMovedFacts(tx, followUp, refused) : null);
}
async function ownerRestartedSince(engine: BrainEngine, refused: WriteRequest[]): Promise<boolean> {
const worktrees = [...new Set(refused.map(row => row.worktree_id).filter((id): id is string => !!id))];
const since = refused.map(row => new Date(row.completed_at ?? row.updated_at ?? 0).getTime()).reduce((a, b) => Math.max(a, b), 0);
const [row] = await engine.executeRaw<{ stale: boolean }>(`SELECT EXISTS (SELECT 1 FROM persistence_consumers c
WHERE c.mode IN ('full','promoted') AND c.renewed_at>now()-($2::integer*interval '1 millisecond') AND c.started_at<=$3::timestamptz
AND (cardinality($1::uuid[])=0 OR c.host_id IN (SELECT owner_host_id FROM persistence_worktrees WHERE id=ANY($1::uuid[])))) AS stale`,
[worktrees, CONSUMER_LIVE_MS, new Date(since).toISOString()]);
return !row?.stale;
}
/**
* #6506 (UC1): the same walk for an input-keyed batch whose entity request was
* refused because a candidate's exact claim had been forgotten. Older batches
* were admitted before automatic extraction skipped withdrawn candidates, so
* the stored refusal (`invalid_params` with the fact_withdrawn message, or the
* typed `error_detail.origin = 'withdrawal'`, which a withdrawal committed
* between preparation and locked validation also leaves) would replay on every
* run of the unchanged input. The follow-up re-admits the retained facts under
* `withdrawn: 'skip'`; no extraction runs again and the historical receipts
* stay as they were.
*/
async function followWithdrawalRefusals(engine: BrainEngine, session: ManagedFactsSession, stored: WriteRequest[]): Promise<WriteRequest[]> {
return followRefusals(engine, session, stored, 'withdrawal-retry', withdrawalRefusal, readmitWithdrawnFacts);
}
/**
* #7602: two extractions target one entity page and the other publishes first, so this batch's entity request, admitted
* at the revision it read, is refused `revision_conflict` at preparation or publication. The retained facts never
* depended on the entity's content: the follow-up re-admits them at the page's current revision, no extraction runs
* again, and the historical receipt stays as it was. A page deleted or replaced since keeps the refusal. Each batch is
* settled first, so a follow-up that loses the race again is followed within the same run.
*/
async function followEntityMoves(engine: BrainEngine, session: ManagedFactsSession, rows: WriteRequest[]): Promise<WriteRequest[]> {
const settle = async (batch: WriteRequest[]) => {
const settled: WriteRequest[] = [];
for (const row of batch) settled.push(isTerminal(row) ? row
: session.wait.observe((await awaitWrite(engine, row, session.config, { waitMs: session.wait.ms(), signal: session.signal })).row));
return settled;
};
return followRefusals(engine, session, await settle(rows), 'entity-moved-retry', isEntityMovedRefusal, readmitMovedFacts, settle);
}
function withdrawalRefusal(row: WriteRequest): boolean {
return withdrawnFromDetail(row.error_detail) !== undefined || row.error_code === 'invalid_params' && row.error_message === FACT_WITHDRAWN_MESSAGE;
}
/**
* While every request of the latest batch is terminal and each uncommitted
* entity request is a `refused` refusal that kept its facts for this input,
* look for the next follow-up batch (`digest([batchKey, label, n])`), or admit
* it through `readmit`, at most MAX_FILE_REFUSAL_RETRIES times. With `settle`
* (partial mode), only the matching refusals are followed, each admitted batch
* is settled before the next look, and every other entity request of the batch,
* and a matching one `readmit` left out, is carried as it stands.
*/
async function followRefusals(engine: BrainEngine, session: ManagedFactsSession, stored: WriteRequest[], label: string,
refused: (row: WriteRequest) => boolean,
readmit: (engine: BrainEngine, followUp: ManagedFactsSession, refused: WriteRequest[]) => Promise<WriteRequest[] | null>,
settle?: (batch: WriteRequest[]) => Promise<WriteRequest[]>): Promise<WriteRequest[]> {
const carried: WriteRequest[] = [];
let latest = stored;
for (let retry = 1; retry <= MAX_FILE_REFUSAL_RETRIES; retry++) {
if (latest.some(row => !isTerminal(row))) break;
const uncommitted = latest.filter(row => isEntityRequest(row) && row.state !== 'committed');
const followed = uncommitted.filter(row => refused(row) && (row.intent as ManagedFactIntent | null)?.facts?.length
&& (row.intent as ManagedFactIntent).inputDigest === session.inputDigest);
const retained = followed.map(row => row.intent as ManagedFactIntent);
if (!followed.length || !settle && followed.length !== uncommitted.length
|| retained.some(intent => !sameSignature(intent.embedding, retained[0]!.embedding))) break;
const followUpKey = digest([session.batchKey, label, retry]);
const followUp: ManagedFactsSession = { ...session, batchKey: followUpKey, embedding: retained[0]!.embedding ?? null,
completionRequestId: managedFactRequestId(followUpKey, '__managed_facts_complete__') };
const admitted = await storedBatch(engine, followUp) ?? await readmit(engine, followUp, followed);
if (!admitted) break;
carried.push(...latest.filter(row => isEntityRequest(row)
&& (row.state === 'committed' || !followed.includes(row) || !admitted.some(next => next.slug === row.slug))));
latest = settle ? await settle(admitted) : admitted;
}
return [...carried, ...latest];
}
function sameSignature(a: FactEmbeddingSignature | null | undefined, b: FactEmbeddingSignature | null | undefined): boolean {
return JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
}
/**
* #6048: admit the refused requests' retained facts as `followUp` with
* `withdrawn: 'skip'`, or return null (nothing admitted) while any refused page
* still fails the canonical file check. Each refused request must still be
* authorized under its stored authority and its page under the current writer
* grant; facts target the page's current revision and are never wider than the
* current default visibility. No extraction runs again.
*/
async function readmitRefusedFacts(engine: BrainEngine, followUp: ManagedFactsSession, refused: WriteRequest[]): Promise<WriteRequest[] | null> {
const { sourceId, remote } = followUp.authority;
const activePack = (await loadActivePackForEngine(engine, { remote, sourceId }).catch(() => null))?.manifest;
const narrowed = await retainedVisibility(engine);
const entities: ManagedFactsEntityInput[] = [];
for (const row of refused) {
await authorizeStoredRequest(engine, row);
await authorizeWrite(engine, followUp.authority, 'extract_facts', row.slug);
const page = await engine.readPageSnapshot(row.slug, { sourceId });
if (!page) return null;
try {
await prepareFileTarget(engine, { source_id: sourceId, worktree_id: followUp.binding?.worktree_id ?? null, slug: row.slug }, page, null, undefined, { activePack, remote });
} catch (refusal) {
if (refusal instanceof OperationError) return null;
throw refusal;
}
const { expected_revision: _refusedRevision, facts, ...kept } = row.intent as ManagedFactIntent;
entities.push({ slug: row.slug, pageId: page.page.id, intent: { ...kept, batchKey: followUp.batchKey, withdrawn: 'skip', expected_revision: page.revision,
facts: facts!.map(narrowed) } });
}
return admitManagedFactsBatch(engine, followUp, regroupParts(followUp.batchKey, entities), entities.some(entity => entity.intent.facts!.some(fact => fact.embedding != null)));
}
/**
* #6506: admit the refused requests' retained facts as `followUp` with
* `withdrawn: 'skip'`. Each refused request must still be authorized under
* its stored authority and its page under the current writer grant; facts
* target the entity page's current revision (the retained origin revision is
* re-checked at preparation) and are never wider than the current default
* visibility. No extraction runs again.
*/
async function readmitWithdrawnFacts(engine: BrainEngine, followUp: ManagedFactsSession, refused: WriteRequest[]): Promise<WriteRequest[] | null> {
const { sourceId } = followUp.authority;
const narrowed = await retainedVisibility(engine);
const entities: ManagedFactsEntityInput[] = [];
for (const row of refused) {
await authorizeStoredRequest(engine, row);
await authorizeWrite(engine, followUp.authority, 'extract_facts', row.slug);
const page = await engine.readPageSnapshot(row.slug, { sourceId });
const { expected_revision: _refusedRevision, facts, ...kept } = row.intent as ManagedFactIntent;
if (!page && (row.page_id !== null || facts!.some(fact => fact.entity_slug === row.slug))) return null;
entities.push({ slug: row.slug, pageId: page?.page.id ?? null, intent: { ...kept, batchKey: followUp.batchKey, withdrawn: 'skip',
...(page ? { expected_revision: page.revision } : {}), facts: facts!.map(narrowed) } });
}
return admitManagedFactsBatch(engine, followUp, regroupParts(followUp.batchKey, entities), entities.some(entity => entity.intent.facts!.some(fact => fact.embedding != null)));
}
/**
* Retained facts are never wider than the current default visibility. Every follow-up is admitted with
* `withdrawn: 'skip'`, whose preparation and locked validation skip a claim forgotten at any visibility, so a narrowed
* fact never re-saves a claim forgotten at its retained visibility.
*/
async function retainedVisibility(engine: BrainEngine): Promise<(fact: FrozenExtractedFact) => FrozenExtractedFact> {
const privateOnly = await resolveDefaultVisibility(engine) === 'private';
return fact => privateOnly && fact.visibility !== 'private' ? { ...fact, visibility: 'private' } : fact;
}
/**
* #7602: admit the refused requests' retained facts as `followUp` with `withdrawn: 'skip'` at each entity page's current revision. A request whose
* page was deleted or replaced since admission is left out and keeps its refusal; null when none is left. Each refused request must still be authorized
* under its stored authority and its page under the current writer grant; the retained intent is otherwise kept as
* admitted. No extraction runs again.
*/
async function readmitMovedFacts(engine: BrainEngine, followUp: ManagedFactsSession, refused: WriteRequest[]): Promise<WriteRequest[] | null> {
const { sourceId } = followUp.authority;
const narrowed = await retainedVisibility(engine);
const entities: ManagedFactsEntityInput[] = [];
for (const row of refused) {
await authorizeStoredRequest(engine, row);
await authorizeWrite(engine, followUp.authority, 'extract_facts', row.slug);
const page = await engine.readPageSnapshot(row.slug, { sourceId });
if ((page?.page.id ?? null) !== row.page_id) continue;
const { expected_revision: _movedRevision, facts, ...kept } = row.intent as ManagedFactIntent;
entities.push({ slug: row.slug, pageId: row.page_id, intent: { ...kept, batchKey: followUp.batchKey, withdrawn: 'skip',
...(page ? { expected_revision: page.revision } : {}), facts: facts!.map(narrowed) } });
}
if (!entities.length) return null;
return admitManagedFactsBatch(engine, followUp, regroupParts(followUp.batchKey, entities), entities.some(entity => entity.intent.facts!.some(fact => fact.embedding != null)));
}
export async function publishManagedFacts(engine: BrainEngine, session: ManagedFactsSession, ctx: FactsBackstopCtx,
facts: ExtractedFact[], visibility: 'private' | 'world', pageSlug?: string,
options: { supersede?: boolean; explicitContext?: boolean; attributeFallback?: boolean; withdrawn?: 'skip' } = {}): Promise<ManagedFactsResult> {
const embedded = facts.some(fact => fact.embedding !== null && fact.embedding !== undefined);
if (embedded) await assertManagedFactsEmbedding(engine, session.config, session.embedding);
const sourceId = session.authority.sourceId;
const groups = new Map<string, FrozenExtractedFact[]>();
const { holdingHome, refuseUnheldFact } = await import('../facts/held-fact-move.ts');
for (const fact of facts) {
if (ctx.abortSignal?.aborted) throw new DOMException('Fact extraction was aborted before admission.', 'AbortError');
if (ctx.notabilityFilter === 'high-only' && fact.notability !== 'high' || ctx.notabilityFilter === 'medium-and-up' && fact.notability === 'low') continue;
const resolved = fact.entity_slug ? await resolveEntitySlugWithSource(engine, sourceId, fact.entity_slug) : null;
const entitySlug = resolved && resolved.source !== 'fallback_slugify' ? resolved.slug : null;
const attributed = entitySlug ?? (options.attributeFallback && resolved ? resolved.slug : null);
// GST-2492: on a strict source a kept fallback entity is held on its holding page (its folder's under a folder rule).
const home = !entitySlug && attributed ? await holdingHome(engine, sourceId, attributed) : null;
// GST-2635: one no holding page can carry (an exact page rule, an unreadable access state) refuses as remember does, before admission.
if (home && 'refused' in home) await refuseUnheldFact(engine, sourceId, attributed!, home.refused, ctx.remote !== false);
const slug = entitySlug ?? (home && 'slug' in home ? home.slug : 'memory/unattributed');
await authorizeWrite(engine, session.authority, 'extract_facts', slug);
await authorizePageVisibility(engine, session.authority, slug);
const group = groups.get(slug) ?? [];
const context = options.explicitContext ? fact.context ?? null : withSpeakerNote(ctx.speaker, ctx.sourceSlug ?? pageSlug ?? null);
// #5836: an inferred subject carries its provenance note into the fence cell and the row.
group.push({ ...fact, entity_slug: attributed, visibility, context: fact.entity_inferred ? appendContextNote(context, inferenceNote(fact.entity_inferred)) : context,
embedding: fact.embedding ? Array.from(fact.embedding) : null,
valid_from: (factEventTime(fact, ctx) ?? new Date()).toISOString(), valid_until: fact.valid_until?.toISOString() ?? null });
groups.set(slug, group);
}
const inputs: ManagedFactsEntityInput[] = [];
for (const [slug, group] of groups) {
const snapshot = await engine.readPageSnapshot(slug, { sourceId, includeDeleted: true });
if (snapshot?.page.deleted_at || group.some(fact => fact.entity_slug === slug) && !snapshot) throw opError('page_identity_changed', 'The resolved fact entity was removed.',
`Entity page ${slug} in source ${sourceId} was deleted after the facts were resolved to it, so nothing was admitted. Run the extraction again (the same request_id is safe: nothing was accepted); it resolves entities against the current pages.`,
{ fix: pageFix(sourceId, slug) });
const intent: ManagedFactIntent = { kind: 'managed_facts_entity', batchKey: session.batchKey,
inputDigest: session.inputDigest, origin: session.origin, originalRequestId: session.originalRequestId,
embedding: session.embedding ?? null, ...(options.supersede ? { supersede: true as const } : {}),
...(options.attributeFallback ? { attribute_fallback: true as const } : {}),
...(options.withdrawn === 'skip' ? { withdrawn: 'skip' as const } : {}),
...(session.captureSource ? { capture_source: session.captureSource } : {}),
...(session.derivation ? { derivation: session.derivation } : {}),
...(snapshot ? { expected_revision: snapshot.revision } : {}), facts: group };
inputs.push(...entityParts(session.batchKey, { slug, pageId: snapshot?.page.id ?? null, intent }));
}
const admitted = await admitManagedFactsBatch(engine, session, inputs, embedded, ctx.abortSignal);
return collectManagedFacts(engine, session, session.entityMoveRetry ? await followEntityMoves(engine, session, admitted) : admitted);
}
interface ManagedFactsEntityInput { slug: string; pageId: number | null; intent: ManagedFactIntent }
/**
* #6898 follow-up: one entity's facts as requests of at most MANAGED_FACTS_PUBLICATION_MAX facts. A group
* within the cap stays one request, exactly as before. Every part targets the revision the batch read; a
* later part also accepts the revision its committed predecessor left (facts-prepare.ts).
*/
/** A follow-up batch re-admits refused parts: an entity's retained facts are rejoined in part order and split again. */
function regroupParts(batchKey: string, inputs: ManagedFactsEntityInput[]): ManagedFactsEntityInput[] {
const bySlug = new Map<string, ManagedFactsEntityInput>();
for (const { intent: { part: _part, ...intent }, ...input } of inputs) {
const seen = bySlug.get(input.slug);
bySlug.set(input.slug, seen ? { ...seen, intent: { ...seen.intent, facts: [...seen.intent.facts!, ...intent.facts!] } } : { ...input, intent });
}
return [...bySlug.values()].flatMap(input => entityParts(batchKey, input));
}
function entityParts(batchKey: string, input: ManagedFactsEntityInput): ManagedFactsEntityInput[] {
const facts = input.intent.facts!;
if (facts.length <= MANAGED_FACTS_PUBLICATION_MAX) return [input];
const of = Math.ceil(facts.length / MANAGED_FACTS_PUBLICATION_MAX);
const ids = Array.from({ length: of }, (_, i) => managedFactRequestId(batchKey, input.slug, i + 1));
return ids.map((_, i) => ({ ...input, intent: { ...input.intent,
facts: facts.slice(i * MANAGED_FACTS_PUBLICATION_MAX, (i + 1) * MANAGED_FACTS_PUBLICATION_MAX),
part: { index: i + 1, of, deferred_facts: Math.max(0, facts.length - (i + 1) * MANAGED_FACTS_PUBLICATION_MAX), follow_up: ids.slice(i + 1) } } }));
}
/** One transaction: the session's per-entity fact requests, then the completion request that names them. */
async function admitManagedFactsBatch(engine: BrainEngine, session: ManagedFactsSession, inputs: ManagedFactsEntityInput[],
embedded: boolean, signal?: AbortSignal): Promise<WriteRequest[]> {
const sourceId = session.authority.sourceId;
return engine.transaction(async tx => {
await assertAmbientCaptureAdmissible(tx, session.captureSource);
if (embedded) await assertManagedFactsEmbedding(tx, session.config, session.embedding, true);
const children: string[] = [];
const accepted: WriteRequest[] = [];
for (const input of [...inputs, { slug: '__managed_facts_complete__', pageId: null, intent: {
kind: 'managed_facts_complete', batchKey: session.batchKey, inputDigest: session.inputDigest,
origin: session.origin, originalRequestId: session.originalRequestId, children,
...(session.captureSource ? { capture_source: session.captureSource } : {}) } as ManagedFactIntent }]) {
if (signal?.aborted) throw new DOMException('Fact extraction was aborted before admission.', 'AbortError');
await authorizePageVisibility(tx, session.authority, input.slug);
const requestId = input.intent.kind === 'managed_facts_complete' ? session.completionRequestId
: managedFactRequestId(session.batchKey, input.slug, input.intent.part?.index);
const row = await admitWriteInTransaction(tx, { principal: session.authority.principal, authority: session.authority,
operation: 'extract_facts', sourceId, sourceIncarnation: session.authority.sourceIncarnation,
worktreeId: session.binding?.worktree_id, topologyGeneration: session.binding?.topology_generation,
requestId, slug: input.slug, pageId: input.pageId, callerIntent: input.intent, intent: input.intent });
accepted.push(row);
if (input.intent.kind === 'managed_facts_entity') children.push(row.id);
}
return accepted;
});
}