dsh-ds-balance 1.0.0

package/lib/http/routes.d.ts

@@ -0,0 +1,63 @@
+/**
+ * 用 `ctx.connection.fetch` 注册全部 HTTP 端点。
+ *
+ * 三层职责分得很开：本文件只管**注册**，`handlers.ts` 管**怎么做**，
+ * `wire.ts` 管**长什么样**。注册需要 `ctx`，所以只有本文件碰宿主。
+ *
+ * 契约要点（docs/backend-architecture.md §3.3 / §8.2）：
+ * - `path` 写死精确值、不带尾随斜杠（实现是 Map 精确键匹配）；
+ * - `requestBody` 必填；
+ * - 物理载体**已先做完信任与浏览器鉴权**，handler 不必再判一次。
+ * @module dsh-ds-balance/http/routes
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { handleBalance, handleHealthz, handleRefresh, handleTestConnection, type HttpDeps } from './handlers.js';
+/**
+ * `/api/v1/config` 的方法分发。
+ *
+ * **写操作走 POST 而不是 PUT**：`ConnectionFetchMethod` 只有 `GET` / `HEAD` / `POST`
+ * 三档，PUT 注册即被拒。契约文档写的是 PUT，以平台实际能力为准。
+ * @param request - 已通过信任与鉴权的请求。
+ * @param deps - 注入的依赖。
+ * @returns 读或写的响应。
+ */
+declare function handleConfigRoute(request: Request, deps: HttpDeps): Promise<Response>;
+/**
+ * 路由表。
+ *
+ * 同一 `path` 只能注册一次，方法在表里合并 —— 实现按 pathname 精确取一条，
+ * 再看方法集合是否命中。`readonly` 与 `as const` 是为了让字面量类型活下来。
+ */
+export declare const HTTP_ROUTES: readonly [{
+    readonly path: "/api/v1/balance";
+    readonly methods: readonly ["GET"];
+    readonly handle: typeof handleBalance;
+}, {
+    readonly path: "/api/v1/balance/refresh";
+    readonly methods: readonly ["POST"];
+    readonly handle: typeof handleRefresh;
+}, {
+    readonly path: "/api/v1/config";
+    readonly methods: readonly ["GET", "POST"];
+    readonly handle: typeof handleConfigRoute;
+}, {
+    readonly path: "/api/v1/test-connection";
+    readonly methods: readonly ["POST"];
+    readonly handle: typeof handleTestConnection;
+}, {
+    readonly path: "/api/v1/healthz";
+    readonly methods: readonly ["GET"];
+    readonly handle: typeof handleHealthz;
+}];
+/**
+ * 注册全部端点。
+ *
+ * 每个 `register` 都把 effect 挂在 `ctx` 上，所以随 fiber 卸载一起撤销；
+ * 返回的合成 disposer 收拢这五条，供组装点放到生命周期结尾。
+ * @param ctx - 宿主上下文；**必须已经能取到 `connection`**。
+ * @param deps - 注入的依赖。
+ * @returns 撤销全部路由的异步 disposer。
+ */
+export declare function registerHttpRoutes(ctx: Context, deps: HttpDeps): () => Promise<void>;
+export {};
+//# sourceMappingURL=routes.d.ts.map

package/lib/http/routes.js

@@ -0,0 +1,61 @@
+/**
+ * 用 `ctx.connection.fetch` 注册全部 HTTP 端点。
+ *
+ * 三层职责分得很开：本文件只管**注册**，`handlers.ts` 管**怎么做**，
+ * `wire.ts` 管**长什么样**。注册需要 `ctx`，所以只有本文件碰宿主。
+ *
+ * 契约要点（docs/backend-architecture.md §3.3 / §8.2）：
+ * - `path` 写死精确值、不带尾随斜杠（实现是 Map 精确键匹配）；
+ * - `requestBody` 必填；
+ * - 物理载体**已先做完信任与浏览器鉴权**，handler 不必再判一次。
+ * @module dsh-ds-balance/http/routes
+ */
+import { handleBalance, handleConfigGet, handleConfigUpdate, handleHealthz, handleRefresh, handleTestConnection, } from './handlers.js';
+/**
+ * `/api/v1/config` 的方法分发。
+ *
+ * **写操作走 POST 而不是 PUT**：`ConnectionFetchMethod` 只有 `GET` / `HEAD` / `POST`
+ * 三档，PUT 注册即被拒。契约文档写的是 PUT，以平台实际能力为准。
+ * @param request - 已通过信任与鉴权的请求。
+ * @param deps - 注入的依赖。
+ * @returns 读或写的响应。
+ */
+async function handleConfigRoute(request, deps) {
+    return request.method === 'GET'
+        ? handleConfigGet(request, deps)
+        : handleConfigUpdate(request, deps);
+}
+/**
+ * 路由表。
+ *
+ * 同一 `path` 只能注册一次，方法在表里合并 —— 实现按 pathname 精确取一条，
+ * 再看方法集合是否命中。`readonly` 与 `as const` 是为了让字面量类型活下来。
+ */
+export const HTTP_ROUTES = [
+    { path: '/api/v1/balance', methods: ['GET'], handle: handleBalance },
+    { path: '/api/v1/balance/refresh', methods: ['POST'], handle: handleRefresh },
+    { path: '/api/v1/config', methods: ['GET', 'POST'], handle: handleConfigRoute },
+    { path: '/api/v1/test-connection', methods: ['POST'], handle: handleTestConnection },
+    { path: '/api/v1/healthz', methods: ['GET'], handle: handleHealthz },
+];
+/**
+ * 注册全部端点。
+ *
+ * 每个 `register` 都把 effect 挂在 `ctx` 上，所以随 fiber 卸载一起撤销；
+ * 返回的合成 disposer 收拢这五条，供组装点放到生命周期结尾。
+ * @param ctx - 宿主上下文；**必须已经能取到 `connection`**。
+ * @param deps - 注入的依赖。
+ * @returns 撤销全部路由的异步 disposer。
+ */
+export function registerHttpRoutes(ctx, deps) {
+    const disposers = HTTP_ROUTES.map((route) => ctx.connection.fetch.register({
+        path: route.path,
+        methods: route.methods,
+        requestBody: 'buffered',
+        fetch: (request) => route.handle(request, deps),
+    }));
+    return async () => {
+        await Promise.all(disposers.map((dispose) => dispose()));
+    };
+}
+//# sourceMappingURL=routes.js.map

package/lib/http/wire.d.ts

@@ -0,0 +1,82 @@
+/**
+ * 线上形状与序列化。
+ *
+ * 契约见 docs/backend-architecture.md §8：**金额一律八位小数字符串**，
+ * `bigint` 最小单位只活在进程内。本模块是纯函数，不碰 `ctx`、不发请求。
+ * @module dsh-ds-balance/http/wire
+ */
+import type { BalanceView, CacheState, Currency, Severity } from '../domain/balance.js';
+import type { ErrorInfo } from '../domain/errors.js';
+/** 一个币种的余额，金额是八位小数字符串。 */
+export interface WireBalance {
+    currency: Currency;
+    total: string;
+    granted: string;
+    toppedUp: string;
+}
+/** 一个币种的阈值，金额同样是字符串。 */
+export interface WireThresholdPair {
+    warn: string;
+    critical: string;
+}
+/**
+ * 线上的错误结构。
+ *
+ * `details` **不出去**：它可能带上游原文，属于内部诊断面。
+ */
+export interface WireError {
+    code: string;
+    message: string;
+    retryable: boolean;
+}
+/**
+ * 凭据的只读描述。
+ *
+ * 形状逐字对齐官方 `credentialProvider.describe()`：**只有三个事实，没有装值的槽**。
+ * 界面靠它决定凭据字段是「可编辑」还是「由启动环境提供」。
+ */
+export interface WireCredentialInfo {
+    ref: string;
+    configured: boolean;
+    source: string | null;
+    writable: boolean;
+}
+/** `GET /api/v1/balance` 的响应体。 */
+export interface WireBalanceResponse {
+    requestId: string;
+    schemaVersion: number;
+    state: CacheState;
+    stale: boolean;
+    fetchedAt: number;
+    ageMs: number;
+    isAvailable: boolean;
+    accountTag8: string;
+    balances: WireBalance[];
+    selected: {
+        currency: Currency;
+        total: string;
+    } | null;
+    severity: Severity;
+    thresholds: Record<Currency, WireThresholdPair>;
+    /** 第一版不做「今日已用」；字段保留以维持契约完整。 */
+    todayUsage: null;
+    error: WireError | null;
+}
+/** 生成一个请求标识。只用于把响应与前端的日志对上，不含任何账户信息。 */
+export declare function newRequestId(): string;
+/** 把错误折成线上形状。 */
+export declare function toWireError(info: ErrorInfo): WireError;
+/**
+ * 把领域视图折成线上响应。
+ *
+ * 两处刻意的兜底，都是为了让响应仍能通过前端的字段类型：
+ * - 没有快照时 `fetchedAt` / `ageMs` 记 0（前端把 0 读成「刚刚」，
+ *   与 mock 在空态 / 错误态给的取值一致）；
+ * - 没有快照时 `isAvailable` 记 `false`。
+ * @param view - 服务层给出的视图。
+ * @param accountTag8 - 当前账本标识前 8 位；没有快照时传空串。
+ * @param requestId - 本次请求的标识。
+ * @returns 契约 §8.3 的响应体。
+ */
+export declare function toWireBalanceView(view: BalanceView, accountTag8: string, requestId: string): WireBalanceResponse;
+//# sourceMappingURL=wire.d.ts.map

package/lib/http/wire.js

@@ -0,0 +1,68 @@
+/**
+ * 线上形状与序列化。
+ *
+ * 契约见 docs/backend-architecture.md §8：**金额一律八位小数字符串**，
+ * `bigint` 最小单位只活在进程内。本模块是纯函数，不碰 `ctx`、不发请求。
+ * @module dsh-ds-balance/http/wire
+ */
+import { randomUUID } from 'node:crypto';
+import { formatMoney } from '../domain/money.js';
+import { SCHEMA_VERSION } from '../version.js';
+/** 生成一个请求标识。只用于把响应与前端的日志对上，不含任何账户信息。 */
+export function newRequestId() {
+    return `req_${randomUUID().replaceAll('-', '').slice(0, 16)}`;
+}
+/** 把错误折成线上形状。 */
+export function toWireError(info) {
+    return { code: info.code, message: info.message, retryable: info.retryable };
+}
+/** 把 `bigint` 最小单位折成八位小数字符串。 */
+function amount(units) {
+    return formatMoney(units);
+}
+/** 把一个币种的阈值折成线上形状。 */
+function thresholdPair(pair) {
+    return { warn: amount(pair.warn), critical: amount(pair.critical) };
+}
+/**
+ * 把领域视图折成线上响应。
+ *
+ * 两处刻意的兜底，都是为了让响应仍能通过前端的字段类型：
+ * - 没有快照时 `fetchedAt` / `ageMs` 记 0（前端把 0 读成「刚刚」，
+ *   与 mock 在空态 / 错误态给的取值一致）；
+ * - 没有快照时 `isAvailable` 记 `false`。
+ * @param view - 服务层给出的视图。
+ * @param accountTag8 - 当前账本标识前 8 位；没有快照时传空串。
+ * @param requestId - 本次请求的标识。
+ * @returns 契约 §8.3 的响应体。
+ */
+export function toWireBalanceView(view, accountTag8, requestId) {
+    const thresholds = {};
+    for (const [currency, pair] of Object.entries(view.thresholds)) {
+        thresholds[currency] = thresholdPair(pair);
+    }
+    return {
+        requestId,
+        schemaVersion: SCHEMA_VERSION,
+        state: view.state,
+        stale: view.stale,
+        fetchedAt: view.fetchedAt ?? 0,
+        ageMs: view.ageMs ?? 0,
+        isAvailable: view.isAvailable ?? false,
+        accountTag8,
+        balances: view.balances.map((item) => ({
+            currency: item.currency,
+            total: amount(item.total),
+            granted: amount(item.granted),
+            toppedUp: amount(item.toppedUp),
+        })),
+        selected: view.selected === null
+            ? null
+            : { currency: view.selected.currency, total: amount(view.selected.total) },
+        severity: view.severity,
+        thresholds,
+        todayUsage: null,
+        error: view.error === null ? null : toWireError(view.error),
+    };
+}
+//# sourceMappingURL=wire.js.map

package/lib/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 宿主半边入口。
+ *
+ * 组装点（Layer 5）：登记设置命名空间，把端口实现接上，交出生命周期。
+ * **业务逻辑一律不在本文件** —— 它只做「谁实现哪个端口」这一个决定。
+ *
+ * 注意：宿主半边**没有模块热更**，改了这里要重建并让插件行重新挂载才生效。
+ * @module dsh-ds-balance
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type Config as ConfigShape } from './config.js';
+export { Config, SETTINGS_NAMESPACE } from './config.js';
+export { CURRENCY_AUTO } from './config.js';
+/** 插件名，loader 诊断用。 */
+export declare const name = "ds-balance";
+/**
+ * 运行时服务门禁。**删任何一项都会让 `apply` 静默不跑。**
+ *
+ * - `settings`：登记配置命名空间。
+ * - `credentials`：复用官方模型页配好的 DeepSeek 凭据（阶段 0 已实测命中）。
+ *
+ * `connection` **不列在这里**：缺了它只该丢掉 HTTP 半边，不该让设置与调度一起消失。
+ * 它由 `apply` 内部的 `ctx.inject` 单独把门。
+ */
+export declare const inject: string[];
+/** 服务端盐的文件名。与契约 §6.1 / §10.5 一致，落在 DSH home 下。 */
+export declare const SALT_FILE_NAME = ".salt";
+/**
+ * 组装并交出生命周期。
+ *
+ * 异步是因为盐要从磁盘读；读失败会降级，不阻断挂载。
+ * @param ctx - 宿主上下文。
+ * @param config - 组合层给的配置基线。
+ */
+export declare function apply(ctx: Context, config: ConfigShape): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/lib/index.js

@@ -0,0 +1,210 @@
+/**
+ * 宿主半边入口。
+ *
+ * 组装点（Layer 5）：登记设置命名空间，把端口实现接上，交出生命周期。
+ * **业务逻辑一律不在本文件** —— 它只做「谁实现哪个端口」这一个决定。
+ *
+ * 注意：宿主半边**没有模块热更**，改了这里要重建并让插件行重新挂载才生效。
+ * @module dsh-ds-balance
+ */
+import { randomBytes } from 'node:crypto';
+import { credentialRef } from '@deepseek-ai/dsh-credentials';
+import { dshHomePath } from '@deepseek-ai/dsh-home-paths';
+import { Config, SETTINGS_NAMESPACE, validateThresholds } from './config.js';
+import { DomainCoreStore } from './adapters/domain-core-store.js';
+import { HttpDeepSeekClient } from './adapters/http-deepseek-client.js';
+import { SALT_BYTES, SALT_ENCODING, loadOrCreateSalt } from './adapters/salt-file.js';
+import { createConsoleLogger } from './adapters/console-logger.js';
+import { MemoryMetrics } from './adapters/memory-metrics.js';
+import { registerHttpRoutes } from './http/routes.js';
+import { BalanceService } from './services/balance-service.js';
+import { ConfigService } from './services/config-service.js';
+import { KeyResolver } from './services/key-resolver.js';
+import { Scheduler } from './services/scheduler.js';
+export { Config, SETTINGS_NAMESPACE } from './config.js';
+export { CURRENCY_AUTO } from './config.js';
+/** 插件名，loader 诊断用。 */
+export const name = 'ds-balance';
+/**
+ * 运行时服务门禁。**删任何一项都会让 `apply` 静默不跑。**
+ *
+ * - `settings`：登记配置命名空间。
+ * - `credentials`：复用官方模型页配好的 DeepSeek 凭据（阶段 0 已实测命中）。
+ *
+ * `connection` **不列在这里**：缺了它只该丢掉 HTTP 半边，不该让设置与调度一起消失。
+ * 它由 `apply` 内部的 `ctx.inject` 单独把门。
+ */
+export const inject = ['settings', 'credentials'];
+/** 服务端盐的文件名。与契约 §6.1 / §10.5 一致，落在 DSH home 下。 */
+export const SALT_FILE_NAME = '.salt';
+/**
+ * 这些字段变了才需要重排调度。
+ *
+ * **阈值与展示币种不在里面**：它们不改变上游取数节奏，而 severity 是后端按缓存快照
+ * 现算的。把它们也算进去，用户改一次阈值就会顺带打一次官方接口 ——
+ * 界面只要重新读一次缓存就够了。
+ */
+const SCHEDULE_FIELDS = ['serverRefreshSeconds', 'baseUrl', 'apiKey', 'apiKeyRef'];
+/**
+ * 这次配置变更要不要重排调度。
+ * @param previous - 变更前的配置。
+ * @param next - 变更后的配置。
+ * @returns 需要重排时为真。
+ */
+function affectsSchedule(previous, next) {
+    return SCHEDULE_FIELDS.some((field) => previous[field] !== next[field]);
+}
+/** 系统时钟。 */
+const systemClock = {
+    now: () => Date.now(),
+    timezone: () => 'Asia/Shanghai',
+};
+/** 把未知异常压成一行。 */
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * 读服务端盐；读不出来就退回一份进程内临时盐。
+ *
+ * **临时盐意味着重启后 `accountTag` 全变、旧快照读不回来** —— 降级但不致命，
+ * 所以只记 error 不抛。契约 §19 第 5 条把这件事的后果写进了文档。
+ * @param logger - 日志端口。
+ * @returns 十六进制盐。
+ */
+async function resolveSalt(logger) {
+    try {
+        return await loadOrCreateSalt({ path: dshHomePath(SALT_FILE_NAME) });
+    }
+    catch (error) {
+        logger.error('ds-balance: salt file unavailable, using an ephemeral salt', { error: describe(error) });
+        return randomBytes(SALT_BYTES).toString(SALT_ENCODING);
+    }
+}
+/** 把设置作用域包成配置端口。**每次现读**，不在构造期缓存。 */
+function adaptSettingsScope(scope) {
+    return {
+        get: () => scope.get(),
+        watch: (listener) => scope.watch(listener),
+        update: (patch) => scope.update(patch),
+    };
+}
+/**
+ * 把官方凭据服务收窄成 {@link Credentials}。
+ *
+ * 真实签名要 `CredentialRef`（带 brand 的字符串），端口只认普通 `string`；
+ * 这里用 `credentialRef()` 补上 brand。引用名形状已由 KeyResolver 先校验过。
+ * @param ctx - 宿主上下文。
+ * @returns 端口实现；服务缺席时返回 `undefined`。
+ */
+function credentialsPort(ctx) {
+    let service;
+    try {
+        service = ctx.credentials;
+    }
+    catch {
+        return undefined;
+    }
+    if (service === undefined)
+        return undefined;
+    return {
+        async resolve(ref) {
+            const resolved = await service.resolve(credentialRef(ref));
+            // 未配置时官方回 `undefined`；端口的约定是「值可能为空串」，交给上游判空。
+            return resolved === undefined ? { value: '', source: 'unset' } : { value: resolved.value, source: resolved.source };
+        },
+        describe: (ref) => service.describe(credentialRef(ref)),
+    };
+}
+/**
+ * 接上 `storageDomain` 并交出打开域的函数。
+ *
+ * 它是**可选服务**，而 cordis 不许读没 `inject` 过的服务（直接访问会抛
+ * 「cannot get property ... without inject」），所以必须由 `ctx.inject` 把门；
+ * 服务缺席时句柄保持 `undefined`，存储层据此降级，插件其余部分照常跑。
+ *
+ * 官方 `Domain<S>.table()` 的键类型由 spec 推导，而 {@link DomainLike} 只声明
+ * 「按字符串取表」这一件事；运行时行为一致，所以在这里收窄一次，
+ * 而不是把官方泛型签名抄进端口。
+ * @param ctx - 宿主上下文。
+ * @returns 打开域的函数；服务缺席时抛错，由存储适配器吸收成降级。
+ */
+function connectStorage(ctx) {
+    const handle = {};
+    ctx.inject(['storageDomain'], (storageCtx) => {
+        storageCtx.effect(() => {
+            handle.facility = storageCtx.storageDomain;
+            return () => { handle.facility = undefined; };
+        }, 'ds-balance: storage facility');
+    });
+    return async (spec) => {
+        const facility = handle.facility;
+        if (facility === undefined)
+            throw new Error('storageDomain service is unavailable');
+        return await facility.open(spec);
+    };
+}
+/**
+ * 组装并交出生命周期。
+ *
+ * 异步是因为盐要从磁盘读；读失败会降级，不阻断挂载。
+ * @param ctx - 宿主上下文。
+ * @param config - 组合层给的配置基线。
+ */
+export async function apply(ctx, config) {
+    const logger = createConsoleLogger();
+    const salt = await resolveSalt(logger);
+    // validate 是跨字段约束的落点：schemastery 表达不了「critical < warn」，
+    // 而它拿到的是合并后的完整候选值，抛错即拒绝写入。见 config.ts 的 validateThresholds。
+    const scope = ctx.settings.register(SETTINGS_NAMESPACE, Config, {
+        base: config,
+        validate: validateThresholds,
+    });
+    const configService = new ConfigService({ source: adaptSettingsScope(scope) });
+    // 端口只建一次：KeyResolver 与 HTTP 端点读的是同一份「可不可写」的事实。
+    const credentials = credentialsPort(ctx);
+    const keys = new KeyResolver({
+        readConfig: () => {
+            const current = configService.current();
+            return { apiKey: current.apiKey, apiKeyRef: current.apiKeyRef };
+        },
+        credentials,
+        logger,
+    });
+    const client = new HttpDeepSeekClient();
+    const store = new DomainCoreStore({ open: connectStorage(ctx), logger });
+    // 默认组合没有指标 sink，所以用内存登记表把聚合值留下来，
+    // 由 healthz 的 metrics 段暴露（见 .agents/notes 的决策）。
+    const metrics = new MemoryMetrics();
+    const service = new BalanceService({
+        client, store, keys, config: configService, clock: systemClock, salt, logger, metrics,
+    });
+    const scheduler = new Scheduler({ target: service, logger });
+    ctx.effect(() => {
+        const stopWatching = scope.watch((next, previous) => {
+            if (affectsSchedule(previous, next))
+                scheduler.reset();
+        });
+        let stopped = false;
+        // 先恢复落盘快照再起调度，否则首拉之前的窗口里界面会闪一次空态。
+        void service.restore().then(() => {
+            if (!stopped)
+                scheduler.start();
+        });
+        return () => {
+            stopped = true;
+            stopWatching();
+            scheduler.stop();
+            // 句柄由调用方关闭：facility 不绑消费方 fiber（契约 §10.0）。
+            void store.close();
+        };
+    }, 'ds-balance: lifecycle');
+    ctx.inject(['connection'], (connectionCtx) => {
+        connectionCtx.effect(() => {
+            const disposeRoutes = registerHttpRoutes(connectionCtx, {
+                service, config: configService, keys, client, store, scheduler, logger, metrics, credentials,
+            });
+            return () => { void disposeRoutes(); };
+        }, 'ds-balance: http routes');
+    });
+}
+//# sourceMappingURL=index.js.map

package/lib/ports/clock.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 时钟端口。时间必须可注入，测试里不许依赖真实时钟。
+ * @module dsh-ds-balance/ports/clock
+ */
+/** 时间来源。 */
+export interface Clock {
+    /** 当前时刻（毫秒）。 */
+    now(): number;
+    /** 账本使用的时区。 */
+    timezone(): 'Asia/Shanghai';
+}
+//# sourceMappingURL=clock.d.ts.map

package/lib/ports/clock.js

@@ -0,0 +1,6 @@
+/**
+ * 时钟端口。时间必须可注入，测试里不许依赖真实时钟。
+ * @module dsh-ds-balance/ports/clock
+ */
+export {};
+//# sourceMappingURL=clock.js.map

package/lib/ports/core-store.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 快照存储端口。实现走 dsh 官方存储接缝，见 docs/backend-architecture.md §10。
+ * @module dsh-ds-balance/ports/core-store
+ */
+import type { BalanceSnapshot } from '../domain/balance.js';
+/** 端口健康。 */
+export interface StoreHealth {
+    ok: boolean;
+    detail?: string;
+}
+/** 快照持久化。 */
+export interface CoreStore {
+    /** 追加一条快照。 */
+    saveSnapshot(snapshot: BalanceSnapshot): Promise<void>;
+    /**
+     * 读取该账本最近一条快照。
+     *
+     * **必须按 `accountTag` 过滤**：凭据轮换后 tag 会变，旧快照不得混用。
+     * @param accountTag - 账本作用域标识。
+     * @returns 最近一条快照，或 `null` 表示该账本还没有记录。
+     */
+    loadLatestSnapshot(accountTag: string): Promise<BalanceSnapshot | null>;
+    /** 端口自检。 */
+    health(): Promise<StoreHealth>;
+    /** 释放存储句柄。**必须由调用方在 `ctx.effect` 的 disposer 里调用。** */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=core-store.d.ts.map

package/lib/ports/core-store.js

@@ -0,0 +1,6 @@
+/**
+ * 快照存储端口。实现走 dsh 官方存储接缝，见 docs/backend-architecture.md §10。
+ * @module dsh-ds-balance/ports/core-store
+ */
+export {};
+//# sourceMappingURL=core-store.js.map

package/lib/ports/credentials.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 凭据端口。
+ *
+ * 契约来自 dsh 的 credentials 服务：`resolve` 回值，`describe` **只回三片**、
+ * 永不回值。装配里可能**没有** credentials seam，消费方必须自己兜。
+ * @module dsh-ds-balance/ports/credentials
+ */
+/** 解析结果。 */
+export interface ResolvedCredential {
+    value: string;
+    source: string;
+}
+/** 描述结果：**类型里根本没有装值的槽**。 */
+export interface CredentialDescription {
+    configured: boolean;
+    source?: string;
+    writable: boolean;
+}
+/** 凭据服务的最小面。 */
+export interface Credentials {
+    /**
+     * 解析一个引用名。
+     * @param ref - 环境变量名形状的引用名。
+     * @throws 引用名非法或没有该凭据时抛错。
+     */
+    resolve(ref: string): Promise<ResolvedCredential>;
+    /** 描述一个引用名。 */
+    describe(ref: string): Promise<CredentialDescription>;
+}
+//# sourceMappingURL=credentials.d.ts.map

package/lib/ports/credentials.js

@@ -0,0 +1,9 @@
+/**
+ * 凭据端口。
+ *
+ * 契约来自 dsh 的 credentials 服务：`resolve` 回值，`describe` **只回三片**、
+ * 永不回值。装配里可能**没有** credentials seam，消费方必须自己兜。
+ * @module dsh-ds-balance/ports/credentials
+ */
+export {};
+//# sourceMappingURL=credentials.js.map

package/lib/ports/deepseek-client.d.ts

@@ -0,0 +1,47 @@
+/**
+ * DeepSeek 上游端口。
+ * @module dsh-ds-balance/ports/deepseek-client
+ */
+import type { ErrorCode } from '../domain/errors.js';
+import type { RawBalanceResponse } from '../domain/balance.js';
+/** 默认端点。契约 §3.2：**端点独立**，不继承对话适配器的 baseURL。 */
+export declare const DEFAULT_BASE_URL = "https://api.deepseek.com";
+/** 一次调用的公共参数。 */
+export interface DeepSeekCallOptions {
+    /** 端点基址，可覆盖默认值。 */
+    baseUrl: string;
+    /** 已解析出的明文密钥。**只在本进程内存里流转，不落盘、不记日志。** */
+    apiKey: string;
+    /** 超时毫秒数。 */
+    timeoutMs: number;
+    /** 调用方的取消信号。 */
+    signal?: AbortSignal;
+}
+/** 测连接的结果，形状对齐契约 §8.7。 */
+export interface TestConnectionResult {
+    ok: boolean;
+    latencyMs: number;
+    isAvailable?: boolean;
+    balances?: Array<{
+        currency: string;
+        total: string;
+    }>;
+    code?: ErrorCode;
+    message?: string;
+}
+/** 余额上游。 */
+export interface DeepSeekClient {
+    /**
+     * 抓一次余额。
+     * @throws {UpstreamError} 上游返回非 2xx。
+     * @throws {TimeoutError} 超时。
+     * @throws {NetworkError} 连不上。
+     * @throws {ParseError} 响应不是 JSON。
+     */
+    fetchBalance(options: DeepSeekCallOptions): Promise<RawBalanceResponse>;
+    /**
+     * 测连接。**不动活动缓存。** 失败时返回 `ok: false` 而不抛错。
+     */
+    testConnection(options: DeepSeekCallOptions): Promise<TestConnectionResult>;
+}
+//# sourceMappingURL=deepseek-client.d.ts.map

package/lib/ports/deepseek-client.js

@@ -0,0 +1,7 @@
+/**
+ * DeepSeek 上游端口。
+ * @module dsh-ds-balance/ports/deepseek-client
+ */
+/** 默认端点。契约 §3.2：**端点独立**，不继承对话适配器的 baseURL。 */
+export const DEFAULT_BASE_URL = 'https://api.deepseek.com';
+//# sourceMappingURL=deepseek-client.js.map