import { FileMemoryEngineBackend, type TaskSpec } from "@sema-agent/core";
import type { ServiceConfig } from "./config-types.js";
/** 前缀词表本体(供门/诊断读;判定一律走 {@link isV2ScopeKey},别在别处重写 startsWith 链)。 */
export declare const V2_SCOPE_PREFIXES: readonly string[];
/**
 * 一个 scope 键是否带 v2 typed 前缀。
 *
 * ⚠️ 判据刻意停在**前缀**层,不升级成 core 的 `parseScopeKey`:后者对「带可识别前缀但结构坏」的键
 * 是 fail-loud 抛错,而本谓词的两个调用点都只是在决定「要不要挂 v2 标 / 要不要再包一层」——把抛点
 * 挪到这里会把 core 的校验时机整体前移(行为面改动,不在本条案的射程内)。坏键仍由 core 在它自己的
 * 校验点 fail-loud。
 */
export declare function isV2ScopeKey(key: string): boolean;
/** Resolve the memory scope for a request ([ref] S1 — the file-based memory engine is the only plane).
 *
 *  SINGLE-USER (REQUIRE_PRINCIPAL !== "true"): ONE shared scope — `config.memoryScope` (default "local"),
 *  regardless of any principal label the caller self-reports (a single-user worker's `anon:*` / ad-hoc
 *  principals are surface labels, not isolation identities — keying memory by them would split the one
 *  user's memory across surfaces). Explicit `MEMORY_SCOPE` wins (it IS config.memoryScope).
 *
 *  MULTI-TENANT (REQUIRE_PRINCIPAL=true): always `undefined` ⇒ no `spec.memory` ⇒ memory is DARK,
 *  fail-closed. The engine's file basement carries NO tenant isolation (one shared directory tree), so
 *  handing tenants per-principal scopes over it would be a cross-tenant bleed surface; until a
 *  tenant-isolated backend exists, multi-tenant memory is off by construction. */
/** R5(批γ):memory scope 列宽(两方言 VARCHAR(190) 同宽)。principal 上限 190 **字符**在
 *  security.ts 把身份轴守住了,但 `formatUserScope`/`formatProjScope` 的段编码(百分号转义)会
 *  **膨胀**——非 ASCII principal 编码后可超列宽,此前落裸 SQL 错。产出处响亮拒,错误可分类。
 *
 *  [ref] 件1:定义**搬去** `plugins/memory-key-guards.ts`(列宽与 store 写口同源单一属主),此处
 *  只再导出——旧 import 路径(本文件)逐字不变,`memoryScopeFor` 的产出处消费点也不变。 */
export { MEMORY_SCOPE_COLUMN_CHARS, assertMemoryScopeWidth } from "./plugins/memory-key-guards.js";
export declare function memoryScopeFor(config: ServiceConfig, principal?: string, projectId?: string): string | undefined;
/**
 * N0 (通宵测试 2026-07-09,三重坐实 e2b+kata+代码): the file memory engine (core [ref]) materializes and
 * harvests via `node:fs` on the WORKER's local fs, while a remote exec lane routes the model's file tools to
 * the SANDBOX fs — the planes never meet: materialized memory is invisible inside the sandbox (the injected
 * instructions burn failing Write turns) and sandbox writes are never harvested (add=0). Until core defines
 * the boundary (engine routed through the ExecutionEnv seam, or host-only by contract — relayed on the team
 * channel), a remote lane forces memory DARK unless the operator explicitly vouches both lanes share one fs
 * (`MEMORY_ENGINE_REMOTE_LANE=allow`, e.g. ssh to a host on the same NFS mount).
 *
 * Pure posture probe (memoryEngineBackendFor consumes it; main.ts logs it): `undefined` = no plane split
 * (no remote lane, or the `host` lane), `dark` = split + fail-closed, `forced` = split + operator override.
 */
export declare function memoryEngineRemoteLanePosture(config: ServiceConfig): {
    lane: string;
    posture: "dark" | "forced";
} | undefined;
/**
 * N0 启动告警的**文案**(纯,可单测;boot/stores.ts 的装配点只负责喂「引擎这一腿真的接上了吗」并打日志)。
 *
 * 为什么要按引擎真身分腿(2026-08-12 复扫,已核真):{@link memoryEngineRemoteLanePosture} 的 `dark` 只对
 * **file** 引擎腿有裁决权 —— 车道门的唯一消费者是 {@link memoryEngineBackendFor}。`MEMORY_ENGINE_BACKEND=pg|tidb`
 * 的两条腿在 boot/stores.ts 里**先于**任何车道判断就被点亮(库是持久真身,与手的文件平面无关),于是同一次
 * 启动会先打 `memory_engine_enabled {enabled:true, backend:"pg"}`,几行之后再打一句「memory dark
 * (fail-closed) … Set MEMORY_ENGINE_REMOTE_LANE=allow」—— 两句直接对撞,而且把运维指向一个在该腿上**不接线**
 * 的旋钮(`memoryEngineRemoteLaneAllowed` 的读者只有本文件与那条日志)。日志是运维唯一能看见的部署事实,
 * 一句谎比没有这句更贵。
 *
 * 返回 `undefined` = 本部署没什么可说的(无平面分裂车道 / 记忆整体关 / 多租户 file 腿的 dark 成因是租户隔离,
 * 已由 `memory_engine_enabled` 的 reason 位报因,不在这里重复)。
 */
export declare function buildMemoryRemoteLaneWarn(config: ServiceConfig, 
/** 记忆引擎这一腿**真的**接上了吗(`memoryEngine !== undefined`)——装配结果,不在本函数里重算。 */
engineWired: boolean): {
    lane: string;
    effect: string;
} | undefined;
/**
 * [ref] S1 wiring gate (pure — unit-testable without booting main): build the file-based memory-engine
 * backend for this deployment, or `undefined` when memory must stay dark.
 *
 *  - SINGLE-USER TURNKEY ONLY (`requirePrincipal !== true`): the engine's file basement
 *    (`FileMemoryEngineBackend` over one directory tree) has NO tenant isolation, so a multi-tenant
 *    deployment gets `undefined` — memory dark, fail-closed (never a shared cross-tenant store).
 *  - `MEMORY_ENGINE=off` (`config.memoryEngineEnabled === false`) is the explicit operator kill-switch.
 *  - REMOTE EXEC LANE (N0): a plane-splitting lane (any non-`host` remoteExec) forces `undefined` — memory
 *    dark, fail-closed — unless `MEMORY_ENGINE_REMOTE_LANE=allow` (see memoryEngineRemoteLanePosture above).
 *  - Directory: `<root>/memory` where root = `resolveMemoryEngineRoot(config.memoryEngineDir ?? fallbackRoot)`
 *    (explicit `MEMORY_ENGINE_DIR` → caller's data root → `AGENT_DATA_DIR` env → `~/.ai-agent`). The
 *    FileBackend PINS this directory (core §2.7: `directoryRoot` wins over per-repo derivation), so the
 *    single user has ONE memory home across repos/tasks — the CC `~/.claude` posture.
 *
 * Returns the backend + the resolved config root (the root also rides on `RunnerDeps.memoryEngineDir` so
 * core derives the B3 control plane beside it).
 */
/**
 * S-133(7.59.0 合并重扫 wf_5ac18676 #1)—— **引擎数据根的唯一推导点**。模型是用 fs 工具往这里写记忆的
 * ([ref] 记忆边界不变式,boot/memory-boundary.ts),所以三件事必须读**同一只**值:①boot 起哪只记忆后端的根
 * (boot/stores.ts 三腿)、②`RunnerDeps.memoryEngineDir`、③守卫集 `createSensitivePathPolicy` 的 `dataRoot`
 * (deployment-governance.ts:落在这个根**里面**的目标按相对根判,根自己的祖先段不算目标的账)。
 * 此前 ③ 读的是 `config.localDataRoot`(本地**店**根:`LOCAL_DATA_ROOT → CONFIG_LOCAL_DIR → AGENT_DATA_DIR`),
 * 而 ① 的 file 腿读的是 `MEMORY_ENGINE_DIR ?? AGENT_DATA_DIR`——两条链在「店根另指他处 + 记忆根坐在守卫段下
 * (壳布局 `~/.sema/engine-data`)」时分家 ⇒ 记忆库每一次 Write 被硬拒(7.58.0 放行 ⇒ 回归);反向
 * (`CONFIG_LOCAL_DIR=~/.sema` 当 dataRoot)则让配置根自身免检。两根本就是两件事:店根归誊本门,引擎根归本函数。
 *
 * 形与 boot/stores.ts 逐字同律:DB 记忆腿(pg/tidb)的根 = `<localDataRoot ?? fallbackRoot>/memory-work`
 * (per-worker 物化区);file 腿 = `resolveMemoryEngineRoot(memoryEngineDir ?? fallbackRoot)`。**不判引擎是否
 * 启用**——纯路径推导,禁用态下守卫仍以「若开引擎会写到哪」为根,与 core 缺省(`$AGENT_DATA_DIR`)同向。
 */
export declare function memoryEngineRootFor(config: Pick<ServiceConfig, "memoryEngineBackend" | "memoryEngineDir" | "localDataRoot">, fallbackRoot?: string): string;
/** file 后端的根链(`MEMORY_ENGINE_DIR ?? fallback ?? $AGENT_DATA_DIR ?? ~/.ai-agent`)—— 与后端选择器**无关**:
 *  `memoryEngineBackendFor` 恒造 file 后端(run-local 从 env 继承 `MEMORY_ENGINE_BACKEND=pg|tidb` 时仍是 file),
 *  所以它的根必须走这条链而不是 `memoryEngineRootFor` 的分派(codex 修复验证轮 [medium]:分派会把 run-local 的
 *  记忆搬到 `<localDataRoot>/memory-work`,存量记忆与控制面升级后隐形)。 */
export declare function fileMemoryEngineRoot(config: Pick<ServiceConfig, "memoryEngineDir">, fallbackRoot?: string): string;
/** 本部署 file 记忆引擎的**平面三坐标**(根 / 记忆目录 / 控制面目录)—— {@link fileMemoryPlaneFor} 一次算齐。 */
export interface FileMemoryPlane {
    readonly root: string;
    readonly memoryDir: string;
    readonly controlDir: string;
}
/**
 * S-215(B-085)—— **file 记忆引擎平面的单铸点**,兼这条腿的**接线门**。
 *
 * 为什么是一只函数而不是两处各自推导:平面坐标有**两个**消费者 —— ① {@link memoryEngineBackendFor}
 * 钉给 `FileMemoryEngineBackend` 的 `memoryDir` + `controlDir`;② local 车道的 capture opt-out **记录店**
 * (`StoreBackend.sessionCaptureRecords()` 喂 core 的 `fileSessionCaptureRecordStore(controlDir)`)。
 * 两者必须是**同一只目录**,否则声明写进 A、引擎读 B ⇒ 一条被「受理」的隐私声明在引擎面根本不存在,
 * 那比一句诚实的 409 更坏。两处各写一份推导链 = 哪天根链改了只改一处的必然漂移,所以推导(根 → 记忆目录 →
 * 控制面目录,三步都在这里、只写一遍)与门合并在此(合并复审 R37:此前 `join(root, "memory")` 在本函数与
 * `memoryEngineBackendFor` 各写一份 —— 记忆目录规则有了第二个写者,现已收回一处)。
 *
 * 返回 `undefined` ⇔ 本部署上 file 记忆引擎**不接线**(多租户 / `MEMORY_ENGINE=off` / 平面分裂车道未 allow)。
 * 门与 `memoryEngineBackendFor` 逐字同源(它就读本函数),所以「有引擎 ⇔ 有控制面 ⇔ 供记录店」三者
 * 在构造上不可能分家。
 *
 * 🔴 **core 7.16.0 起每个 scope 的家深一层**(`<memoryDir>/<label>`,缺省 scope `local` ⇒ `memory/local/`),
 * 而本函数**一个坐标都不用改**:①`memoryDir` 仍是引擎的**平面**(家是它的直接子目录,由引擎自己按注册簿
 * 铸 —— 本仓绝不自行 `join(memoryDir, scope)`,label 的真源是注册簿,写家的读面是 core 的
 * `writableRootOf(handle)`);②`controlDir` 的推导键仍是记忆目录本身(亲读 `layout.js` 的
 * `deriveControlPlaneDir(configRoot, key) = join(configRoot, slugifyPath(resolve(key)), ".engine")`,[ref] 未动),
 * 所以升级前写下的 capture opt-out 记录、账本、隔离区全部原址可读。升级期的一次性搬家由引擎在 mount 前跑
 * (`adoptRootScopeLayout`),披露走 incident 座(见 {@link memoryEngineBackendFor} 的 `onIncident`)。
 * 机器钉:`test/memory-layout-plane.test.ts`。
 */
export declare function fileMemoryPlaneFor(config: ServiceConfig, fallbackRoot?: string): FileMemoryPlane | undefined;
/** 控制面目录那一坐标(local 车道 capture 记录店的依托)—— 只是 {@link fileMemoryPlaneFor} 的投影,不是第二条推导。 */
export declare function fileMemoryControlDirFor(config: ServiceConfig, fallbackRoot?: string): string | undefined;
/**
 * 引擎的**挂载平面**那一坐标 —— 已装配的 backend 钉了就是它(`directoryRoot`;file 腿 = `<root>/memory`),
 * 没钉就是配置根。
 *
 * ## 为什么需要这只谓词(而不是让各处自己 `join(root, "memory")` 或直接用配置根)
 * 本仓把「引擎根」(`RunnerDeps.memoryEngineDir` = 配置根,core 在它旁边派生控制面与各任务的记忆目录)
 * 与「挂载平面」(引擎真正读写条目的那棵树)**两只坐标**在装配结果里压成了一只 `root`,于是凡是要后者的
 * 消费点都拿了前者 —— 差一层。`core 7.16.0` 之前这条差错也在(条目在 `<root>/memory/*.md`,消费点按
 * `<root>/*.md` 找),只是没有任何一道门看得见;[ref] 把条目再下移一层之后它照样静默。
 *
 * 判据与 core **同源**、不是第二条推导:`dist/core/runner/prepare-memory.js` 的
 * `const pinned = backend.directoryRoot; … typeof pinned === "string" && pinned ? pinned : <派生>`
 * 逐字同形。鸭子读(`MemoryBackend` 的类型面不声明这一位,core 自己也是鸭子读)与
 * `backendOwnsControlPlane` 同族 —— 认能力不认后端方言名。
 *
 * 两只 SQL 记忆孪生不钉平面(盘上只有每任务的 ephemeral 投影,boot 期没有第二个说得出口的坐标)⇒
 * 回到配置根,读数与本函数出现之前**逐字节相同**。
 */
export declare function memoryMountRootOf(backend: unknown, configRoot: string): string;
export declare function memoryEngineBackendFor(config: ServiceConfig, fallbackRoot?: string, 
/** 引擎 backend 的**构造期 incident 座**(core `FileMemoryEngineBackendOptions.onIncident`)。
 *  接它不是锦上添花:backend 的每个无锁公开面在动注册簿派生的路径前会跑一次布局收编
 *  (`ensureLayout`),而**那条腿上唯一的披露口就是构造期这只座** —— mount 那条腿拿的是引擎自己的座。
 *  不接 ⇒ 一次真搬家(`memory.layout_migrated`)或一堆无主根内容(`memory.layout_unowned_root_content`)
 *  在这条腿上**静默**发生。缺席合法(advisory-silent,与操作面三件套同形)。 */
onIncident?: (err: Error & {
    code?: string;
}) => void): {
    backend: FileMemoryEngineBackend;
    root: string;
} | undefined;
/**
 * MF-30 memory PAUSE (option B, per-request — clay 2026-06-27): build the `TaskSpec.memory` spec for ONE run from
 * the resolved memory `scope` + the request's `memoryWrite` toggle. `memoryWrite === false` ⇒ `writeScope: null`
 * ([ref] engine read-only: normalizeMemorySpec's writeScope:null — materialize/read still works, harvest
 * commits nothing). Absent/true ⇒ normal read+write. No scope (engine off / multi-tenant dark) ⇒ undefined
 * (memory feature off for this run). Pure (testable in isolation) — main.ts's resolveSpec composes it with the
 * engine-backend presence guard.
 *
 * 🔴 **三轴正交**(S-405 起;三者可任意并存,互不吞):`memoryWrite:false` = 本 run 只读平面(挂、读、
 * harvest 不提交)· `memoryCapture:"off"` = 采集面关(挂、读、本会话内容永不进长期记忆)· `memory:"off"` =
 * **整面关**(`enabled:false`,这一次连记忆面都不挂)。后两者从 `declarations` 进(键名与 wire 逐字同名)。
 */
export declare function memorySpecForRequest(scope: string | undefined, memoryWrite: boolean | undefined, defaultScopes?: string[], 
/** [ref] 件A([ref] 件3④):origin 盖章的部署形态维(N2)。`multiTenant=true`(requirePrincipal)
 *  ⇒ 登记簿 defaultScopes 的 org 键按 **request** 盖章(条目由调用方 projectId 选定=caller 可影响的
 *  选择器,core 准入门据此过目录判决);单用户 ⇒ 一律 deployment(operator 登记簿条目归 deployment,
 *  否则单用户部署被自家规则整拒——v4 §0 伤害①的成立前提)。缺参=旧调用形,不盖章(整键缺席=
 *  core legacy 语义,零迁移)。 */
originPolicy?: {
    multiTenant: boolean;
}, 
/** 请求体上的**单成员闭集声明**(键名与 wire 逐字同名,零翻译;拼写门的唯一属主是
 *  `request-value-closure.ts`,两腿共用 —— 到这里的值已经过门,只可能是 `"off"` 或缺席)。
 *
 *  · `memoryCapture:"off"`([ref] §2.1,[ref])⇒ `TaskSpec.memory.capture:"off"`:**采集面**关 ——
 *    记忆照常挂、照常读,但本会话的内容永远不进长期记忆(core 落一条单向会话记录,按部署姿态 + verdict 裁)。
 *  · `memory:"off"`(core [ref] r5 §5 W3,S-405)⇒ `TaskSpec.memory.enabled:false`:**整面**关 ——
 *    这一次运行不挂记忆面。**保留事实不折缺席**(codex r2 #4):core 的终局观测面把「有 spec 但被关」读作
 *    `reason:"disabled"`、把「整键缺席」读作 `reason:"no-spec"`,审计上不是一件事;而 `normalizeMemorySpec`
 *    在 scopes 为空时整体返回 `undefined`,所以**关的那一形也必须带正常 scopes**。
 *
 *  两键与 `memoryWrite`(本 run 只读平面)在**铸型上**三轴正交、可并存,本函数不替谁做取舍;
*  整键缺席 ⇒ 都不铸(形状逐字节不变=additive 锁)。
*  ⚠️ **铸型正交 ≠ 裁决正交**(亲核 core 7.21.1 `dist/core/runner/prepare-memory.js`):core 把
*  capture 腿与引擎挂载**合取**(`captureDeclared = captureDeclaredRaw && useMemoryEngine`),所以
*  `memory:"off"` 那一 turn 上 capture 的**单向会话记录不落**(core 发 `phase:"config"` 一行响亮披露)。
*  两键同发要不要一起送、送了买到什么,口径全文在契约 §12.7;钉在 memory-off-request.test.ts ⑤。 */
declarations?: {
    memory?: "off";
    memoryCapture?: "off";
}): {
    scopes: string[];
    writeScope?: string | null;
    scopeContract?: "v2";
    scopeOrigins?: Record<string, "deployment" | "request">;
    capture?: "off";
    enabled?: false;
} | undefined;
/**
 * 「这一腿挂不挂记忆面」的**唯一属主**(合并复审 车HF F1,2026-09-18):与 core `prepareMemory` 的判据同源 ——
 * `normalizeMemorySpec(spec)?.enabled === true`。S-405 之后 `memory:"off"` 铸的是「键在场 + `enabled:false`」(保留事实),
 * 任何按「键在不在场」判挂没挂的读者从那一天起都读错(改前 `memory-notice` 正是那样,把无记忆面的披露一起吞掉)。
 * 消费方拿本函数的布尔,不拿 `spec.memory` 自己判。
 *
 * ⚠️ **本函数会抛,而「抛」本身就是一条判据**(S-424 补注)。`normalizeMemorySpec` 对两形直接 throw
 * (亲核安装态 core 7.22.0 `dist/core/memory.js` 的 `normalizeMemorySpec`):
 *  · 单数 `scope` 键在场 ⇒ `code:"config.memory_scope_spelling"`(core 已删的旧拼写;它的报错原话
 *    是「Refusing to start with memory silently off」—— 静默关闭正是那次 HIGH 的伤害面);
 *  · `capture` 在场且不是字面 `"off"` ⇒ `code:"config.memory_capture_spelling"`。
 *
 * 这两形在本仓的 wire 面上**都到不了这里**,各有属主:
 *  · 请求体侧 = 值闭包门 `singleMemberOffFieldIssue`(`src/request-value-closure.ts`;fresh 400 与 resume
 *    重放共用的同一只)—— 到得了下游的 `memory`/`memoryCapture` 只可能是字面 `"off"` 或缺席;
 *  · spec 侧 = 唯一铸点 {@link memorySpecForRequest}(本文件)—— 它恒产 `scopes: [scope, ...extras]`,
 *    从不产单数 `scope`,`capture` 也只在声明为 `"off"` 时才铸。
 *
 * 所以这里抛 = **调用方没先过值闭包门**(手搓 spec、或绕过铸点直接喂一份 `TaskSpec.memory`),不是这一腿
 * 的运行期异常,**不要在本函数里加吞异常的臂**:吞掉就退回「memory 静默整体关闭」,即上面那条报错原话
 * 拒绝的那件事。要放宽/收紧值域,改上面两个属主。
 */
export declare function memoryFaceMounted(memory: TaskSpec["memory"]): boolean;
//# sourceMappingURL=memory-scope.d.ts.map