berry-agent-sdk 0.1.0-alpha.2

package/dist/src/context/events.js

@@ -0,0 +1,161 @@
+/**
+ * 事件分派四模式（04 §6「作用域与事件四模式」后半——分派契约）。
+ *
+ * 四模式（模式是事件契约的一部分）：
+ *  - emit：广播——全部监听器各跑各，异常互相隔离（单腿炸不波及他腿与调用方）；
+ *  - waterfall：串行管线——监听器必须调 next() 委托、不调即短路（管线后段
+ *    不再执行；守门行语义依赖它）；异常沿链传播（管线失败）；
+ *  - parallel：全体并发，Promise.all 收口（异常传播）；
+ *  - serial：排队串行（不短路，与 waterfall 的区别 = 无委托链）；异常隔离
+ *    不停后段（上报后继续）。
+ *
+ * 词汇纪律：自定义事件名走域名前缀（件/插件域）；未注册词 emit/on 均
+ * fail-loud（EVENT_NOT_REGISTERED）、撞名 EVENT_DUPLICATE 拒静默覆盖。
+ */
+import { BaseError } from '../contracts/index.js';
+/**
+ * 事件分派器：词汇注册表 + 四模式派发。一个 ctx 一枚（装载运行时的通信契约
+ * 单源——双实现 = 通信割裂）。
+ */
+export class EventDispatch {
+    /** 词汇注册表（name → 已注册标记；单源执法面） */
+    registered = new Set();
+    /** 监听器表（name → 注册序监听器列表；on 返回退订闭包；泛型在存储侧擦除为 unknown、取回侧 cast 还原） */
+    listeners = new Map();
+    /** serial 排队尾（per-name 链式 promise——排队串行） */
+    serialQueues = new Map();
+    /** 隔离腿异常上报（缺省 stderr 直写；装配根接 logger） */
+    onListenerError;
+    constructor(options) {
+        this.onListenerError =
+            options?.onListenerError ??
+                ((eventName, err) => {
+                    // 缺省面：stderr 直写（context 自身的 logger 尚未装配——先有鸡问题）
+                    console.error(`[context] 事件监听器异常（${eventName}）`, err);
+                });
+    }
+    /** 注册事件词汇（装载期声明面）；撞名拒 EVENT_DUPLICATE（禁静默覆盖） */
+    registerEventNames(names) {
+        for (const name of names) {
+            if (this.registered.has(name)) {
+                throw new BaseError('EVENT_DUPLICATE', `事件词汇 ${name} 已注册——拒静默覆盖（词汇注册表单源）`);
+            }
+            this.registered.add(name);
+        }
+    }
+    /** 判别词汇是否已注册（装配断言/诊断面） */
+    isRegistered(name) {
+        return this.registered.has(name);
+    }
+    /**
+     * 挂通知型监听器（emit/serial 共用监听面——同词两模式收同一监听器形态）。
+     * 词未注册拒 EVENT_NOT_REGISTERED（fail-loud 禁散播未声明事件名）。
+     * @returns 退订闭包（消费方经 scope.effect 组合生命周期）
+     */
+    on(name, listener) {
+        this.assertRegistered(name);
+        const list = this.listeners.get(name) ?? [];
+        const entry = { notify: listener };
+        list.push(entry);
+        this.listeners.set(name, list);
+        return () => {
+            const current = this.listeners.get(name);
+            if (!current)
+                return;
+            const idx = current.indexOf(entry);
+            if (idx >= 0)
+                current.splice(idx, 1);
+        };
+    }
+    /**
+     * 广播：全部监听器并发各跑各，异常互相隔离（单腿炸不波及他腿与调用方——
+     * 上报 onListenerError 后照常收口）。
+     */
+    async emit(name, data) {
+        this.assertRegistered(name);
+        const legs = (this.listeners.get(name) ?? []).map((entry) => entry.notify);
+        await Promise.all(legs.map(async (listener) => {
+            try {
+                await listener?.(data);
+            }
+            catch (err) {
+                this.onListenerError(name, err);
+            }
+        }));
+    }
+    /**
+     * 串行管线：监听器必须调 next(value) 委托——不调即短路（管线后段不再执行，
+     * 返回值为该监听器的产出）；异常沿链传播（管线失败语义——守门行依赖）。
+     */
+    async waterfall(name, value) {
+        this.assertRegistered(name);
+        // 存储侧泛型擦除为 unknown——取回 cast 还原为本次调用的 T（注册/派发两侧的
+        // 类型对齐由调用方契约保证，这里只做类型往返）
+        const chain = (this.listeners.get(name) ?? []).map((entry) => entry.waterfall).filter(Boolean);
+        // 自尾向头组合：每层 next 即下一段；尾 = 直通（value 原样出管线）
+        let next = (v) => Promise.resolve(v);
+        for (const listener of chain.reverse()) {
+            const downstream = next;
+            next = (v) => Promise.resolve(listener(v, downstream));
+        }
+        return next(value);
+    }
+    /** 挂管线监听器（waterfall 专用面——与 on 分开：形态不同防误用） */
+    onWaterfall(name, listener) {
+        this.assertRegistered(name);
+        const list = this.listeners.get(name) ?? [];
+        const entry = { waterfall: listener };
+        list.push(entry);
+        this.listeners.set(name, list);
+        return () => {
+            const current = this.listeners.get(name);
+            if (!current)
+                return;
+            const idx = current.indexOf(entry);
+            if (idx >= 0)
+                current.splice(idx, 1);
+        };
+    }
+    /**
+     * 全体并发，Promise.all 收口（异常传播——与 emit 的区别即异常语义）。
+     * 监听器面与 on 共用（通知型返回值参与收口）。
+     */
+    async parallel(name, data) {
+        this.assertRegistered(name);
+        const legs = (this.listeners.get(name) ?? []).map((entry) => entry.notify);
+        const results = await Promise.all(legs.map((listener) => Promise.resolve(listener ? listener(data) : undefined)));
+        // 监听器返回面 unknown（通知型契约）——收口侧由调用方以 R 断言（并发计算型的
+        // 类型对齐是调用方契约，存储侧无从静态验证）
+        return results;
+    }
+    /**
+     * 排队串行：逐监听器顺序执行（后段等前段完成）；不短路——异常隔离上报后
+     * 继续下一段（与 waterfall 的区别 = 无委托链、异常不停段）。
+     * 同词多次派发按到达序排队（per-name 链式 promise）。
+     */
+    serial(name, data) {
+        this.assertRegistered(name);
+        const legs = (this.listeners.get(name) ?? []).map((entry) => entry.notify);
+        const tail = this.serialQueues.get(name) ?? Promise.resolve();
+        const run = tail.then(async () => {
+            for (const listener of legs) {
+                try {
+                    await listener?.(data);
+                }
+                catch (err) {
+                    this.onListenerError(name, err);
+                }
+            }
+        });
+        // 队尾吞异常（隔离语义：一次派发的失败不堵后续派发的排队）
+        this.serialQueues.set(name, run.then(() => undefined, () => undefined));
+        return run;
+    }
+    /** 未注册词执法（emit/on/waterfall/parallel/serial 共用） */
+    assertRegistered(name) {
+        if (!this.registered.has(name)) {
+            throw new BaseError('EVENT_NOT_REGISTERED', `事件词 ${name} 未注册——fail-loud（词汇注册表单源，先 registerEventNames）`);
+        }
+    }
+}
+//# sourceMappingURL=events.js.map

package/dist/src/context/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../../../../src/context/events.ts"],"names":[],"mappings":"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"}

package/dist/src/context/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * context 模块公开面（L1 运行时基座——02 §2.2；一切件在其上）。
+ *
+ * 本批落码：作用域（effect LIFO 回卷/fork 级联/stale 护栏）+ 事件分派四模式
+ * + provide/get 服务注册表 + 自写 logger + canonical 工作区根。
+ * jiti 加载原语与目录信任判定随 host 装载批定形（消费面 = 插件装载器——
+ * 契约先于实现的纵切序），02 §2.2 职责清单不变。
+ */
+import './codes.js';
+export { Scope, SCOPE_EFFECT_CAPACITY } from './scope.js';
+export type { Disposer } from './scope.js';
+export { EventDispatch } from './events.js';
+export type { NotifyListener, WaterfallListener, ListenerErrorReporter } from './events.js';
+export { LogLevelState, createLogger, childLogger } from './logger.js';
+export type { LogLevel, LogSink, Logger } from './logger.js';
+export { canonicalWorkspaceRoot, clearWorkspaceRootCache } from './workspace.js';

package/dist/src/context/index.js

@@ -0,0 +1,14 @@
+/**
+ * context 模块公开面（L1 运行时基座——02 §2.2；一切件在其上）。
+ *
+ * 本批落码：作用域（effect LIFO 回卷/fork 级联/stale 护栏）+ 事件分派四模式
+ * + provide/get 服务注册表 + 自写 logger + canonical 工作区根。
+ * jiti 加载原语与目录信任判定随 host 装载批定形（消费面 = 插件装载器——
+ * 契约先于实现的纵切序），02 §2.2 职责清单不变。
+ */
+import './codes.js';
+export { Scope, SCOPE_EFFECT_CAPACITY } from './scope.js';
+export { EventDispatch } from './events.js';
+export { LogLevelState, createLogger, childLogger } from './logger.js';
+export { canonicalWorkspaceRoot, clearWorkspaceRootCache } from './workspace.js';
+//# sourceMappingURL=index.js.map

package/dist/src/context/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../src/context/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,YAAY,CAAC;AAEpB,OAAO,EAAE,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAE1D,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAEvE,OAAO,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/src/context/logger.d.ts

@@ -0,0 +1,67 @@
+/**
+ * 自写轻量 logger（07 §6 日志级别策略——约百行，不引入日志库）。
+ *
+ * 细则逐条：
+ *  - 级别四档 error/warn/info/debug + silent 全静默；缺省 info（发布物即生产）；
+ *  - 结构化 JSON 行（time/level/module/msg + 上下文字段）写 stderr；
+ *  - 模块前缀分级：BERRY_AGENT_LOG_LEVEL 逗号分隔 per-module 条目
+ *    （`info,session:debug`）；条目按 lastIndexOf(':') 切分（模块名含冒号可表达
+ *    ——`core:memory` 里的冒号不是分隔符）；前缀匹配（`session` 命中 `session`
+ *    与 `session:*` 全体）；
+ *  - 共享阈值盒：同盒树的 logger 持同一盒引用，setLevel 改盒值全树即时生效；
+ *    child logger 不入登记表（防慢性泄漏）；
+ *  - 无效条目 stderr 警告后跳过（视同未设——静默失效比无反馈更糟）；
+ *  - 纪律红线（消费方义务）：只在 debug 出现的分支，其行为必须同时是 durable
+ *    事件或运行时断言——进程日志职责收窄为「启动/崩溃/守门/恢复」诊断。
+ */
+/** 级别权重（数值越大越啰嗦——debug 3 最详；silent 独立档不入权重表） */
+declare const LEVEL_WEIGHTS: {
+    readonly error: 0;
+    readonly warn: 1;
+    readonly info: 2;
+    readonly debug: 3;
+};
+export type LogLevel = keyof typeof LEVEL_WEIGHTS | 'silent';
+/** 日志输出面（缺省 process.stderr；测试注入内存 sink） */
+export type LogSink = (line: string) => void;
+/**
+ * 阈值盒（共享状态）：全局级 + per-module 前缀覆盖表。
+ * createLogger 树全体持同一盒引用——setGlobalLevel/setModuleLevel 改盒即全树
+ * 即时生效；盒本身即解析态，logger 对象不入任何登记表。
+ */
+export declare class LogLevelState {
+    /** 全局阈值（缺省 info——发布物即生产） */
+    private global;
+    /** per-module 前缀覆盖（前缀 → 级别；匹配取最长前缀） */
+    private readonly modules;
+    /** 从 env 串建盒（无效条目 stderr 警告后跳过——视同未设） */
+    static fromEnv(env: string | undefined, warn?: (msg: string) => void): LogLevelState;
+    /** 改全局阈值（全树即时生效——运行期提降级面） */
+    setGlobalLevel(level: LogLevel): void;
+    /** 设/覆盖某模块前缀阈值（前缀匹配：`session` 命中 `session` 与 `session:*` 全体） */
+    setModuleLevel(prefix: string, level: LogLevel): void;
+    /** 解析模块生效级：最长匹配前缀条目 ?? 全局（silent 压倒一切——显式全静默） */
+    resolve(module: string): LogLevel;
+}
+/** logger 实例形态（模块名绑定的四方法输出器——纯值对象，不入登记表） */
+export interface Logger {
+    readonly module: string;
+    debug(msg: string, fields?: Record<string, unknown>): void;
+    info(msg: string, fields?: Record<string, unknown>): void;
+    warn(msg: string, fields?: Record<string, unknown>): void;
+    error(msg: string, fields?: Record<string, unknown>): void;
+}
+/**
+ * 建模块 logger（child 面共享 state 盒——树内全树同盒即时生效）。
+ * @param module 模块名（域分段用 ':'——如 `session`、`core:memory`）
+ * @param state 共享阈值盒（缺省独立盒 info——测试/独立小面用；ctx 装配时传同一盒）
+ * @param sink 输出面（缺省 process.stderr；测试注入内存）
+ * @param clock 时间源（缺省 Date.now——测试可注入定值）
+ */
+export declare function createLogger(module: string, state?: LogLevelState, sink?: LogSink, clock?: () => number): Logger;
+/**
+ * 派生 child logger（`session` → `session:sqlite` 式域细分）：同盒同 sink 同
+ * clock——setLevel 改盒全树（含 child）即时生效。仅接受 createLogger 产物。
+ */
+export declare function childLogger(parent: Logger, subModule: string): Logger;
+export {};

package/dist/src/context/logger.js

@@ -0,0 +1,137 @@
+/**
+ * 自写轻量 logger（07 §6 日志级别策略——约百行，不引入日志库）。
+ *
+ * 细则逐条：
+ *  - 级别四档 error/warn/info/debug + silent 全静默；缺省 info（发布物即生产）；
+ *  - 结构化 JSON 行（time/level/module/msg + 上下文字段）写 stderr；
+ *  - 模块前缀分级：BERRY_AGENT_LOG_LEVEL 逗号分隔 per-module 条目
+ *    （`info,session:debug`）；条目按 lastIndexOf(':') 切分（模块名含冒号可表达
+ *    ——`core:memory` 里的冒号不是分隔符）；前缀匹配（`session` 命中 `session`
+ *    与 `session:*` 全体）；
+ *  - 共享阈值盒：同盒树的 logger 持同一盒引用，setLevel 改盒值全树即时生效；
+ *    child logger 不入登记表（防慢性泄漏）；
+ *  - 无效条目 stderr 警告后跳过（视同未设——静默失效比无反馈更糟）；
+ *  - 纪律红线（消费方义务）：只在 debug 出现的分支，其行为必须同时是 durable
+ *    事件或运行时断言——进程日志职责收窄为「启动/崩溃/守门/恢复」诊断。
+ */
+/** 级别权重（数值越大越啰嗦——debug 3 最详；silent 独立档不入权重表） */
+const LEVEL_WEIGHTS = { error: 0, warn: 1, info: 2, debug: 3 };
+/**
+ * 阈值盒（共享状态）：全局级 + per-module 前缀覆盖表。
+ * createLogger 树全体持同一盒引用——setGlobalLevel/setModuleLevel 改盒即全树
+ * 即时生效；盒本身即解析态，logger 对象不入任何登记表。
+ */
+export class LogLevelState {
+    /** 全局阈值（缺省 info——发布物即生产） */
+    global = 'info';
+    /** per-module 前缀覆盖（前缀 → 级别；匹配取最长前缀） */
+    modules = new Map();
+    /** 从 env 串建盒（无效条目 stderr 警告后跳过——视同未设） */
+    static fromEnv(env, warn = defaultEnvWarn) {
+        const state = new LogLevelState();
+        if (!env)
+            return state;
+        for (const rawEntry of env.split(',')) {
+            const entry = rawEntry.trim();
+            if (!entry)
+                continue;
+            // lastIndexOf(':') 切分：模块名含冒号（core:memory）可表达——
+            // 最右一个冒号才是「模块:级别」分隔符
+            const sep = entry.lastIndexOf(':');
+            const levelText = sep >= 0 ? entry.slice(sep + 1) : entry;
+            const moduleText = sep >= 0 ? entry.slice(0, sep) : '';
+            const level = parseLevel(levelText);
+            if (!level) {
+                warn(`BERRY_AGENT_LOG_LEVEL 无效条目 "${entry}"（级别 "${levelText}" 不在闭集 error|warn|info|debug|silent）——已跳过`);
+                continue;
+            }
+            if (sep >= 0 && moduleText)
+                state.modules.set(moduleText, level);
+            else
+                state.setGlobalLevel(level);
+        }
+        return state;
+    }
+    /** 改全局阈值（全树即时生效——运行期提降级面） */
+    setGlobalLevel(level) {
+        this.global = level;
+    }
+    /** 设/覆盖某模块前缀阈值（前缀匹配：`session` 命中 `session` 与 `session:*` 全体） */
+    setModuleLevel(prefix, level) {
+        this.modules.set(prefix, level);
+    }
+    /** 解析模块生效级：最长匹配前缀条目 ?? 全局（silent 压倒一切——显式全静默） */
+    resolve(module) {
+        if (this.global === 'silent')
+            return 'silent';
+        let best;
+        for (const [prefix, level] of this.modules) {
+            // 前缀匹配：模块名等于前缀、或以前缀+':' 开头（域分段符）
+            const matches = module === prefix || module.startsWith(`${prefix}:`);
+            if (!matches)
+                continue;
+            if (!best || prefix.length > best.prefix.length)
+                best = { prefix, level };
+        }
+        const resolved = best?.level ?? this.global;
+        return resolved === 'silent' ? 'silent' : resolved;
+    }
+}
+/** 单条级别字面量解析（大小写不敏感；无效返回 null） */
+function parseLevel(text) {
+    const lower = text.toLowerCase();
+    if (lower === 'silent')
+        return 'silent';
+    if (lower in LEVEL_WEIGHTS)
+        return lower;
+    return null;
+}
+/** env 无效值警告的缺省面（bootstrapping 阶段 stderr 一行） */
+function defaultEnvWarn(msg) {
+    process.stderr.write(`[logger] ${msg}\n`);
+}
+/**
+ * logger → 内部三件（盒/sink/clock）弱关联：childLogger 派生的唯一缝。
+ * WeakMap 不阻回收（logger 亡即条目亡——「不入登记表防慢性泄漏」的兑现形态：
+ * 强引用登记表不存在，弱关联只为派生期取参）。
+ */
+const loggerInternals = new WeakMap();
+/**
+ * 建模块 logger（child 面共享 state 盒——树内全树同盒即时生效）。
+ * @param module 模块名（域分段用 ':'——如 `session`、`core:memory`）
+ * @param state 共享阈值盒（缺省独立盒 info——测试/独立小面用；ctx 装配时传同一盒）
+ * @param sink 输出面（缺省 process.stderr；测试注入内存）
+ * @param clock 时间源（缺省 Date.now——测试可注入定值）
+ */
+export function createLogger(module, state = new LogLevelState(), sink = (line) => process.stderr.write(`${line}\n`), clock = Date.now) {
+    const write = (level, msg, fields) => {
+        const resolved = state.resolve(module);
+        if (resolved === 'silent')
+            return;
+        if (LEVEL_WEIGHTS[level] > LEVEL_WEIGHTS[resolved])
+            return;
+        // 结构化 JSON 行：time/level/module/msg + 上下文字段平铺
+        sink(JSON.stringify({ time: clock(), level, module, msg, ...fields }));
+    };
+    const logger = {
+        module,
+        debug: (msg, fields) => write('debug', msg, fields),
+        info: (msg, fields) => write('info', msg, fields),
+        warn: (msg, fields) => write('warn', msg, fields),
+        error: (msg, fields) => write('error', msg, fields),
+    };
+    loggerInternals.set(logger, { state, sink, clock });
+    return logger;
+}
+/**
+ * 派生 child logger（`session` → `session:sqlite` 式域细分）：同盒同 sink 同
+ * clock——setLevel 改盒全树（含 child）即时生效。仅接受 createLogger 产物。
+ */
+export function childLogger(parent, subModule) {
+    const internals = loggerInternals.get(parent);
+    if (!internals) {
+        throw new Error('childLogger 仅接受 createLogger 产物（缺内部面——勿手工构造 Logger 对象）');
+    }
+    return createLogger(`${parent.module}:${subModule}`, internals.state, internals.sink, internals.clock);
+}
+//# sourceMappingURL=logger.js.map

package/dist/src/context/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../../../../src/context/logger.ts"],"names":[],"mappings":"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"}

package/dist/src/context/scope.d.ts

@@ -0,0 +1,78 @@
+/** disposer 形态：同步或异步清理函数（effect 登记的回卷腿）。返回 void——TS 的 void 返回豁免天然吸收 async 腿（Promise 返回值可赋 void 返回位） */
+export type Disposer = () => void;
+/**
+ * effect 总注册帽（03 §3.4：10^4——可用性防线，失控登记不拖垮回卷序）。
+ * 真源即执法位点：自有 disposers 长度即计数，无第二计数位（包装层形否决——
+ * 帽下帽双重记账〔03 §3.4 遗漏审计批钉位〕）；fork 面独立同律（子作用域
+ * 各有自有帽，级联回卷总量不受限）。导出供测试与文档引用。
+ */
+export declare const SCOPE_EFFECT_CAPACITY = 10000;
+/**
+ * 作用域：服务注册面（provide/get）+ 可逆注册面（effect）+ fork 树。
+ * 生命周期三级（进程根/会话/run）= 三次 createScope/fork 的使用形态。
+ */
+export declare class Scope {
+    /** 父作用域（fork 派生关系；根作用域为 undefined） */
+    private readonly parent?;
+    /** 自有服务注册（fork 面继承 = get 沿父链上溯；子重提供同名 = 遮蔽合法） */
+    private readonly services;
+    /**
+     * 服务主位账（同主刷新律——04 §6 定形注：/reload 撬名修复批）。键值与
+     * services 同集（每次成功 provide 同步落位；匿名提供 = undefined 位）。
+     * 刷新判据专用，不另设公共读面。
+     */
+    private readonly owners;
+    /** 已登记 disposer（登记序）——回卷按逆序 LIFO */
+    private readonly disposers;
+    /** 未回卷的子作用域（父回卷时级联先卷） */
+    private readonly children;
+    /** 回卷旗标（stale 护栏判据；回卷后一切迟到登记拒） */
+    private disposed;
+    /** @param parent 父作用域（缺省 = 根作用域）；派生走 fork() 不直调本构造器 */
+    private constructor();
+    /** 创建根作用域（进程根/会话/run 三级的使用入口之一） */
+    static createRoot(): Scope;
+    /**
+     * 派生子作用域：子先于父回卷（逆序天然）、父回卷级联全部未卷子；
+     * provide 面继承（get 上溯）、effect 面独立（子的副作用不污染父的回卷序）。
+     */
+    fork(): Scope;
+    /** 作用域是否已回卷（异步腿竞速收口的 stale 判据） */
+    get isDisposed(): boolean;
+    /**
+     * 登记服务（装载期接线、运行期取用）。
+     * 撞名分档（同主刷新律——04 §6 定形注）：同 owner 重供 = 原位刷新
+     * （upsert——依赖方下次取用即见新值；`/reload` 换代重跑同装配位的结构性
+     * 支撑）；跨主撞名与匿名重供（任一方匿名即不可证明同主）照旧拒
+     * CONTEXT_SERVICE_DUPLICATE（两方抢一名仍是装配 bug）。
+     * owner 真源 = 装载器注入非自报（ctx.provide 恒 = 本插件 id——包装层注入；
+     * 宿主装配位 = 装配位标识）。迟到注册（已回卷）拒 SCOPE_STALE。
+     */
+    provide(name: string, service: unknown, owner?: string): void;
+    /**
+     * 取服务（沿 fork 链上溯——provide 面继承）。
+     * 缺席 fail-loud（CONTEXT_SERVICE_MISSING，拼错名立即炸）。
+     * 判缺席用沿链 has 而非值判 undefined——已注册的 undefined 值服务不算缺席。
+     */
+    get<T>(name: string): T;
+    /** 可选消费（「诚实缺席不 fail-loud」的唯一档——如浏览器引擎缺席） */
+    tryGet<T>(name: string): T | undefined;
+    /**
+     * 沿 fork 链枚举可见服务名（自身 + 全部祖先，就近在前）。
+     * 03 §3.1「服务目录运行时可枚举」的机制腿——ctx.get 缺席报错附现行名单，
+     * 点名错误当场响亮可诊。子遮蔽父同名时两现（就近位次即遮蔽序——诚实枚举）。
+     */
+    serviceNames(): string[];
+    /**
+     * 登记可逆副作用：register 立即执行、其返回的 disposer 进 LIFO 回卷序。
+     * 迟到登记（已回卷）拒 SCOPE_STALE——迟到的 disposer 不再执行（回卷已过，
+     * 补跑只会撕裂状态）。
+     */
+    effect(register: () => Disposer): void;
+    /**
+     * 回卷作用域：子先级联回卷 → 自有 disposer 按 LIFO 逆序回卷 → 标记 disposed。
+     * 幂等（二次调用直接返回）；disposer 异常不中断回卷（清算是尽力序——
+     * 单腿炸不掩护其余腿的清算义务）。
+     */
+    dispose(): Promise<void>;
+}