@yss123/cage-files 0.0.0-stage → 0.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 shunshunyue and Cage contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,100 @@
-# Temporary Holding Version
+# @yss123/cage-files
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Cage 的私有文件服务。管理上传会话、可恢复分片、SHA-256 校验、配额、私有下载和过期清理，内置本地磁盘实现，并提供自定义对象存储适配接口。适合业务附件；字段声明和业务事务内绑定仍由 kernel 负责。
+
+上传完成只得到临时文件 ID，调用业务命令成功后才正式绑定。文件字节、存储路径和公开 URL 不进入业务字段。
+
+## 安装与服务端配置
+
+需要 Node.js 24+、PostgreSQL 和持久存储，与其他 Cage 包保持同版本：
+
+```powershell
+pnpm add @yss123/cage-files
+```
+
+标准 `@yss123/cage-http` 已装配本包。定制存储时在 API 入口配置，以下例子里的 `@app/domain` 来自脚手架应用：
+
+```ts
+/** API 私有文件装配；目录持久保存，不能作为静态资源公开。 */
+import { createServer } from '@yss123/cage-http';
+import { LocalFileStorage } from '@yss123/cage-files';
+import * as domain from '@app/domain';
+
+const server = createServer({
+  domain,
+  files: {
+    storage: new LocalFileStorage('.cage-files'),
+    partBytes: 16 * 1024 * 1024,
+    maxFileBytes: 2 * 1024 ** 3,
+    retentionMs: 24 * 3600_000,
+  },
+});
+await server.listen();
+process.once('SIGINT', () => void server.close());
+process.once('SIGTERM', () => void server.close());
+```
+
+未传 `storage` 时会创建本地实现，目录由 `files.directory`、`CAGE_FILES_DIR` 或默认 `.cage-files` 决定。这个目录不属于可再生的 `.cage`；容器应使用持久卷，数据库元数据与文件字节应配套备份。
+
+## 业务接入的三个步骤
+
+1. 在聚合 `fields` 使用 kernel 的 `file/files`，并在目标用户命令 input 中声明同名 UUID 或 UUID 数组。字段只能位于聚合顶层。
+2. 运行 `pnpm gen`，审查迁移并执行 `pnpm migrate`，授予目标命令及所需读取/范围能力。
+3. 浏览器使用 `client.upload` 上传，成功后将返回 ID 交给目标业务命令；字段绑定与业务记录同事务提交。
+
+字段片段合并到已有聚合，不能单独作为完整 domain：
+
+```ts
+import { files } from '@yss123/cage-kernel';
+
+// 每个文件最多 20 MiB、最多 5 个，仅允许明确的 MIME 类型。
+const attachments = files({
+  maxCount: 5,
+  maxBytes: 20 * 1024 * 1024,
+  accept: ['application/pdf', 'image/png'],
+});
+// 放入聚合 fields: { attachments }；命令 input 需同名 z.array(z.string().uuid())。
+```
+
+下例为采购模板的页面操作，`selectedFile` 来自文件选择框。其他业务应替换目标命令、字段与生成契约：
+
+```ts
+import { client, purchaseOrder } from '@app/contracts';
+
+/** 上传失败会抛错；业务保存失败仍须展示结果，不能把上传成功当作订单已保存。 */
+async function createWithAttachment(selectedFile: File) {
+  const task = client.upload(selectedFile, {
+    command: 'PurchaseOrder.create',
+    field: 'attachments',
+  });
+  try {
+    const uploaded = await task.start();
+    return await purchaseOrder.create({
+      amount: '100.00',
+      items: [{ sku: 'A-01', qty: 1 }],
+      attachments: [uploaded.id],
+    });
+  } finally {
+    task.dispose();
+  }
+}
+```
+
+调用方捕获上传异常并检查返回值 `ok`。修改已有记录时，上传目标还须传 `targetId`。刷新后通过客户端查询本人会话，重新选择原文件，再传 `uploadId` 恢复；SDK 会核对已确认分片内容。
+
+## 公开入口与边界
+
+| 入口 | 作用 |
+| --- | --- |
+| `FileService`、`FileServiceOptions` | 协调授权、会话、配额、上传、下载和清理；通常由 HTTP 层持有 |
+| `LocalFileStorage` | 流式写入、校验、合并及范围读取的磁盘实现 |
+| `FileStorage`、`StoredPart`、`ByteRange` | 自定义存储协议；适配 writePart/complete/read/remove/prune |
+| `beginUploadSchema`、`UploadSession`、`FileInfo` | 服务端输入校验与公开上传/文件描述 |
+
+一个文件只能绑定一个对象的一个字段，不能覆盖原文件；替换需新 ID。下载依当前 Cookie 会话、对象范围和字段引用重新授权，不提供永久公开链接。分片/完成操作的预检查不保证最终命令必定通过。
+
+API 启动后及每分钟执行有界清理；独立持有 `FileService` 时须自行定期调用 `cleanup()`，退出时 `close()`。本地多实例必须共享同一目录，不能只共享数据库。代理需允许分片请求体、关闭上传缓冲并配置合并超时。
+
+目前只内置本地存储；`FileStorage` 不代表已提供 S3/OSS SDK 或签名直传。内容头校验也不等于病毒扫描或完整格式验证。
+
+完整说明：[私有文件字段与断点续传](https://github.com/shunshunyue/cage/blob/main/docs/ai/files.md)。源码与反馈：[GitHub](https://github.com/shunshunyue/cage)。许可证：[MIT](https://github.com/shunshunyue/cage/blob/main/LICENSE)。

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+/** 文件包公开入口：协议、默认磁盘实现、上传会话服务分层导出。
+ * HTTP 层消费 FileService；扩展对象存储时实现 FileStorage；字段声明和事务内绑定仍由内核负责。
+ * 此处只重导出类型与实现，导入模块不会启动清理定时器或创建存储目录。
+ */
+export * from './storage.js';
+export * from './local.js';
+export * from './service.js';

package/dist/index.js

@@ -0,0 +1,8 @@
+/** 文件包公开入口：协议、默认磁盘实现、上传会话服务分层导出。
+ * HTTP 层消费 FileService；扩展对象存储时实现 FileStorage；字段声明和事务内绑定仍由内核负责。
+ * 此处只重导出类型与实现，导入模块不会启动清理定时器或创建存储目录。
+ */
+export * from './storage.js';
+export * from './local.js';
+export * from './service.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC"}

package/dist/local.d.ts

@@ -0,0 +1,46 @@
+import { Readable } from 'node:stream';
+import type { ByteRange, FileStorage, StoredPart } from './storage.js';
+/** 本地磁盘适配器：每个上传 UUID 一个私有目录，分片和最终文件再按执行 token 分离。
+ * 服务层只在短事务中登记结果，本类负责事务外写字节；临时文件校验并 fsync 后才 rename 发布。
+ * 存储目录必须跨服务重启保留，且不能作为静态资源目录；下载必须经过 FileService 授权。
+ */
+export declare class LocalFileStorage implements FileStorage {
+    /** 由规范目录计算的稳定标识；避免修改存储位置后误处理旧会话。 */
+    readonly name: string;
+    /** 单片允许 64 KiB～64 MiB，最多一万片；尾片的实际大小由服务层计算。 */
+    readonly limits: {
+        minPartBytes: number;
+        maxPartBytes: number;
+        maxParts: number;
+    };
+    /** 规范化绝对路径，仅服务端内部使用。 */
+    readonly directory: string;
+    /** 只解析配置并建立身份，不创建目录；目录在首次写入时以私有权限创建。 */
+    constructor(directory?: string);
+    /** 验证服务端上传 ID 后定位目录，禁止调用方把任意路径拼接进存储根。 */
+    private dir;
+    /** 只接受本适配器生成的键格式，并再做绝对路径包含检查；非法键统一按输入错误拒绝。 */
+    private path;
+    /** 流式保存一片：边消费边计算长度/摘要，完整校验后持久化并原子改名。
+     * 同 token 的重试可替换其结果，不同 token 使用不同目标；任何失败都会清理本次临时文件。
+     * 返回存储键只代表字节完成，服务层仍须核对租约后才能把该片记录为已确认。
+     */
+    writePart(upload: string, token: string, source: Readable, o: {
+        bytes: number;
+        sha256: string;
+        signal: AbortSignal;
+    }): Promise<string>;
+    /** 顺序合并已确认分片，再次验证每片长度、摘要与总长度，防止磁盘内容在确认后发生变化。
+     * 异步生成器和 pipeline 保留背压，内存不随文件总大小增长；取消或校验失败不会发布最终键。
+     */
+    complete(upload: string, token: string, parts: readonly StoredPart[], o: {
+        bytes: number;
+        signal: AbortSignal;
+    }): Promise<string>;
+    /** 打开私有内容流，可按闭区间读取。文件不存在等 IO 错误直接上抛，不伪装为空文件。 */
+    read(key: string, range?: ByteRange): Promise<Readable>;
+    /** 幂等删除整个上传目录；只能用于服务层已认领的过期或解绑会话，不能代替业务解绑命令。 */
+    remove(upload: string): Promise<void>;
+    /** 保留唯一已提交的最终对象，回收分片和旧 token 产物；目录已消失视为清理完成。 */
+    prune(upload: string, keepKey: string): Promise<void>;
+}

package/dist/local.js

@@ -0,0 +1,158 @@
+// 私有目录不能挂载为静态资源。逐块写入/校验/合并，内存占用与文件总大小无关。
+import { createReadStream, createWriteStream } from 'node:fs';
+import { mkdir, open, readdir, rename, rm } from 'node:fs/promises';
+import { resolve, join, sep } from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { Readable, Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { cageError } from '@yss123/cage-kernel';
+const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+/** 本地磁盘适配器：每个上传 UUID 一个私有目录，分片和最终文件再按执行 token 分离。
+ * 服务层只在短事务中登记结果，本类负责事务外写字节；临时文件校验并 fsync 后才 rename 发布。
+ * 存储目录必须跨服务重启保留，且不能作为静态资源目录；下载必须经过 FileService 授权。
+ */
+export class LocalFileStorage {
+    /** 由规范目录计算的稳定标识；避免修改存储位置后误处理旧会话。 */
+    name;
+    /** 单片允许 64 KiB～64 MiB，最多一万片；尾片的实际大小由服务层计算。 */
+    limits = { minPartBytes: 64 * 1024, maxPartBytes: 64 * 1024 * 1024, maxParts: 10_000 };
+    /** 规范化绝对路径，仅服务端内部使用。 */
+    directory;
+    /** 只解析配置并建立身份，不创建目录；目录在首次写入时以私有权限创建。 */
+    constructor(directory = process.env.CAGE_FILES_DIR ?? '.cage-files') {
+        this.directory = resolve(directory);
+        // 配置指向另一目录时不能把旧文件误判成已删除；不向元数据暴露真实路径。
+        this.name = `local:v1:${createHash('sha256').update(process.platform === 'win32' ? this.directory.toLowerCase() : this.directory).digest('hex').slice(0, 16)}`;
+    }
+    /** 验证服务端上传 ID 后定位目录，禁止调用方把任意路径拼接进存储根。 */
+    dir(upload) {
+        if (!uuid.test(upload))
+            throw cageError('INVALID_INPUT', '非法上传 ID');
+        return join(this.directory, upload);
+    }
+    /** 只接受本适配器生成的键格式，并再做绝对路径包含检查；非法键统一按输入错误拒绝。 */
+    path(key) {
+        if (!/^[0-9a-f-]{36}\/(part|object)-[0-9a-f-]{36}$/.test(key))
+            throw cageError('INVALID_INPUT', '非法存储键');
+        const [id, name] = key.split('/');
+        const path = resolve(this.dir(id), name);
+        if (!path.startsWith(this.directory + sep))
+            throw cageError('INVALID_INPUT');
+        return path;
+    }
+    /** 流式保存一片：边消费边计算长度/摘要，完整校验后持久化并原子改名。
+     * 同 token 的重试可替换其结果，不同 token 使用不同目标；任何失败都会清理本次临时文件。
+     * 返回存储键只代表字节完成，服务层仍须核对租约后才能把该片记录为已确认。
+     */
+    async writePart(upload, token, source, o) {
+        const key = `${upload}/part-${token}`, destination = this.path(key);
+        await mkdir(this.dir(upload), { recursive: true, mode: 0o700 });
+        const temporary = `${destination}.${randomUUID()}.tmp`;
+        let bytes = 0;
+        const hash = createHash('sha256');
+        const verifier = new Transform({ transform(chunk, _encoding, callback) {
+                bytes += chunk.length;
+                if (bytes > o.bytes) {
+                    callback(cageError('INVALID_INPUT', '分片超过声明长度'));
+                    return;
+                }
+                hash.update(chunk);
+                callback(null, chunk);
+            } });
+        try {
+            await pipeline(source, verifier, createWriteStream(temporary, { flags: 'wx', mode: 0o600 }), { signal: o.signal });
+            if (bytes !== o.bytes || hash.digest('hex') !== o.sha256)
+                throw cageError('INVALID_INPUT', '分片长度或 SHA-256 不匹配');
+            // fsync 后才确认分片，避免成功响应仅表示写入了用户态缓冲。
+            const file = await open(temporary, 'r+');
+            try {
+                await file.sync();
+            }
+            finally {
+                await file.close();
+            }
+            o.signal.throwIfAborted();
+            await rename(temporary, destination);
+            return key;
+        }
+        finally {
+            await rm(temporary, { force: true });
+        }
+    }
+    /** 顺序合并已确认分片，再次验证每片长度、摘要与总长度，防止磁盘内容在确认后发生变化。
+     * 异步生成器和 pipeline 保留背压，内存不随文件总大小增长；取消或校验失败不会发布最终键。
+     */
+    async complete(upload, token, parts, o) {
+        const key = `${upload}/object-${token}`, destination = this.path(key);
+        const temporary = `${destination}.${randomUUID()}.tmp`;
+        const self = this;
+        async function* content() {
+            let total = 0;
+            for (const part of parts) {
+                o.signal.throwIfAborted();
+                let bytes = 0;
+                const hash = createHash('sha256');
+                for await (const chunk of createReadStream(self.path(part.key), { signal: o.signal })) {
+                    bytes += chunk.length;
+                    total += chunk.length;
+                    if (bytes > part.bytes || total > o.bytes)
+                        throw cageError('INVALID_INPUT', '分片内容发生变化');
+                    hash.update(chunk);
+                    yield chunk;
+                }
+                if (bytes !== part.bytes || hash.digest('hex') !== part.sha256)
+                    throw cageError('INVALID_INPUT', '分片内容校验失败');
+            }
+            if (total !== o.bytes)
+                throw cageError('INVALID_INPUT', '文件长度不匹配');
+        }
+        try {
+            await pipeline(Readable.from(content()), createWriteStream(temporary, { flags: 'wx', mode: 0o600 }), { signal: o.signal });
+            const file = await open(temporary, 'r+');
+            try {
+                await file.sync();
+            }
+            finally {
+                await file.close();
+            }
+            o.signal.throwIfAborted();
+            await rename(temporary, destination);
+            return key;
+        }
+        finally {
+            await rm(temporary, { force: true });
+        }
+    }
+    /** 打开私有内容流，可按闭区间读取。文件不存在等 IO 错误直接上抛，不伪装为空文件。 */
+    async read(key, range) {
+        const file = await open(this.path(key), 'r');
+        return file.createReadStream(range ? { start: range.start, end: range.end } : {});
+    }
+    /** 幂等删除整个上传目录；只能用于服务层已认领的过期或解绑会话，不能代替业务解绑命令。 */
+    async remove(upload) {
+        const directory = this.dir(upload);
+        // dir() 校验 UUID，绝对路径必须仍在配置目录内，禁止删除根目录。
+        if (!directory.startsWith(this.directory + sep))
+            throw cageError('INVALID_INPUT');
+        await rm(directory, { recursive: true, force: true, maxRetries: 3 });
+    }
+    /** 保留唯一已提交的最终对象，回收分片和旧 token 产物；目录已消失视为清理完成。 */
+    async prune(upload, keepKey) {
+        const directory = this.dir(upload);
+        if (this.path(keepKey) !== join(directory, keepKey.split('/')[1]))
+            throw cageError('INVALID_INPUT');
+        let entries;
+        try {
+            entries = await readdir(directory);
+        }
+        catch (e) {
+            if (e.code === 'ENOENT')
+                return;
+            throw e;
+        }
+        for (const name of entries)
+            if (name !== keepKey.split('/')[1])
+                await rm(join(directory, name), { force: true });
+    }
+}
+//# sourceMappingURL=local.js.map

package/dist/local.js.map

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

package/dist/service.d.ts

@@ -0,0 +1,162 @@
+import type { Readable } from 'node:stream';
+import { z } from 'zod';
+import { type Ctx, type Kernel } from '@yss123/cage-kernel';
+import type { ByteRange, FileStorage } from './storage.js';
+/** 创建上传的外部输入：命令/字段定位授权边界，targetId 仅用于修改已有对象。
+ * bytes 为正安全整数字节数；filename 仅作下载展示，禁止路径和控制字符；contentType 后续还会验内容。
+ */
+export declare const beginUploadSchema: z.ZodObject<{
+    command: z.ZodString;
+    field: z.ZodString;
+    targetId: z.ZodOptional<z.ZodString>;
+    filename: z.ZodString;
+    bytes: z.ZodNumber;
+    contentType: z.ZodString;
+}, z.core.$strip>;
+/** 通过创建校验后的输入类型；不包含服务端生成的会话 ID、租约或存储路径。 */
+export type BeginUpload = z.infer<typeof beginUploadSchema>;
+/** 已完成分片的公开证明；number 从 1 开始，摘要用于断点续传时确认内容一致。 */
+export interface UploadPart {
+    number: number;
+    bytes: number;
+    sha256: string;
+}
+/** 浏览器可见的上传进度。它不泄露存储键，也不能作为永久下载凭据。 */
+export interface UploadSession {
+    /** 会话与业务入口；targetId 在新建对象场景为 null，绑定后仍保留原上传语境。 */
+    id: string;
+    aggregate: string;
+    field: string;
+    command: string;
+    targetId: string | null;
+    /** 展示文件名、精确总字节数和声明的 MIME；不代表客户端可指定物理存储位置。 */
+    filename: string;
+    bytes: number;
+    contentType: string;
+    /** ready 可交给命令绑定；bound 只能通过业务命令解绑；deleting/deleted 不再接收上传。 */
+    status: 'uploading' | 'completing' | 'ready' | 'bound' | 'deleting' | 'deleted';
+    /** 标准片大小、总片数、已确认片以及 ISO 到期时间；列表摘要的 parts 刻意为空。 */
+    partBytes: number;
+    partCount: number;
+    parts: UploadPart[];
+    expiresAt: string;
+}
+/** 经过当前权限检查后返回的文件描述，不包含可绕过权限的存储 URL。 */
+export interface FileInfo {
+    id: string;
+    filename: string;
+    bytes: number;
+    contentType: string;
+}
+/** 单服务实例的存储策略。所有数值均须为正安全整数，并在构造时校验适配器容量限制。 */
+export interface FileServiceOptions {
+    /** 可替换的私有存储；未提供时使用 LocalFileStorage。 */
+    storage?: FileStorage;
+    /** 默认 .cage-files；使用 storage 时由适配器决定目录。 */
+    directory?: string;
+    /** 标准分片字节数，默认 16 MiB；最后一片按剩余长度收尾。 */
+    partBytes?: number;
+    /** 每文件服务级字节上限，默认 2 GiB；还须满足业务字段自身限制。 */
+    maxFileBytes?: number;
+    /** 单用户未绑定会话累计字节上限，默认 8 GiB。 */
+    maxPendingBytesPerUser?: number;
+    /** 租户所有未删除会话累计声明字节上限，默认 100 GiB。 */
+    maxStoredBytesPerTenant?: number;
+    /** 单用户未绑定会话个数上限，默认 100；与字节配额共同限制占用。 */
+    maxPendingUploadsPerUser?: number;
+    /** 暂存保留时间，单位毫秒，默认一天；过期内容由后台清理回收。 */
+    retentionMs?: number;
+    /** 单次分片/合并 IO 总时限，默认 30 分钟。 */
+    ioTimeoutMs?: number;
+}
+/** 文件业务边界的协调器；实例由 API 生命周期管理，close 会取消并等待本实例在途 IO。
+ * 每次访问重新检查当前身份和策略，不把创建会话时的授权当作后续读写的永久许可。
+ */
+export declare class FileService {
+    readonly kernel: Kernel;
+    /** 持久字节适配器；名称同时写入会话，防止跨存储空间误读或误清理。 */
+    readonly storage: FileStorage;
+    /** 已通过适配器限制校验的分片字节数，供 HTTP 层设置请求体限制。 */
+    readonly partBytes: number;
+    /** 服务级文件大小上限，单位字节。 */
+    readonly maxFileBytes: number;
+    private readonly options;
+    private readonly active;
+    private closing;
+    /** 合并默认策略并做启动期配置校验；不创建上传、不访问存储、不启动定时清理。 */
+    constructor(kernel: Kernel, options?: FileServiceOptions);
+    /** 上传/下载入口仅接受具名 user 身份；流程、任务及匿名上下文不能借此占用私有存储。 */
+    private identity;
+    /** 验证命令能力、文件字段及输入归属；已有对象还要通过当前 read 范围和起始状态检查。
+     * 这里只判断上传资格，最终业务命令仍会独立检查版本、硬约束、不变量和绑定合法性。
+     */
+    private policy;
+    /** 取得当前租户当前上传者的会话，并重新校验业务策略；不存在或存储不匹配统一隐藏为 NOT_FOUND。 */
+    private owned;
+    /** 在调用方事务中锁会话行，串行化修改、完成和取消；调用方应已用 owned/policy 完成授权。 */
+    private locked;
+    /** 可修改性检查与授权分离；过期、已绑定或进入删除阶段的会话不允许迟到写入重新激活。 */
+    private usable;
+    /** 将数据库 bigint/日期与内部状态投影成公开 DTO，只列出确实已有存储键的已确认分片。 */
+    private view;
+    /** 按片号返回内部元数据；仅供已完成所有权检查的调用使用，不能直接作为公开查询入口。 */
+    private parts;
+    /** 创建或重放同一次上传申请。租户咨询锁让多实例在同一短事务内核对并占用配额。
+     * 相同用户的同一幂等键只能对应相同规范请求和存储；超配额抛 RATE_LIMITED，不产生半成品会话。
+     * 此步骤只预留元数据与额度，客户端之后使用返回的 partBytes/partCount 上传字节。
+     */
+    begin(raw: unknown, ctx: Ctx, idempotencyKey: string): Promise<UploadSession>;
+    /** 断点恢复的权威进度查询；返回服务端已确认片清单，客户端不能凭本地发送进度认定上传成功。 */
+    get(id: string, ctx: Ctx): Promise<UploadSession>;
+    /** 查询同一业务入口下本人未过期的可恢复会话，最多一百条；摘要不携带完整分片表。 */
+    list(command: string, field: string, targetId: string | null, ctx: Ctx): Promise<UploadSession[]>;
+    /** 为事务外 IO 管理续租、总时限与停机取消。
+     * 续租丢失或数据库异常即中止信号；run 必须在提交元数据前再次检查信号和 token，避免迟到完成覆盖新执行者。
+     * active 持有 Promise 直到 finally，用于 close 等待真正停止，而非仅发出取消请求。
+     */
+    private lease;
+    /** 上传一片：先锁会话认领片号，再释放事务写存储，最后凭 token 确认结果。
+     * 相同片号和摘要的已完成请求可重放；内容变化或有效租约冲突会拒绝。尾片长度从总大小计算。
+     * IO 失败会销毁输入流并释放属于本 token 的租约，已被其他执行接管的记录保持不动。
+     */
+    putPart(id: string, number: number, sha256: string, source: Readable, ctx: Ctx): Promise<UploadPart>;
+    /** 最多读取首片前 8192 字节检查 MIME；文本仅接受合法 UTF-8 和允许的控制字符。
+     * 这是内容类型核对，不是病毒扫描，也不会验证整个 JSON/CSV 的业务格式。
+     */
+    private verifyType;
+    /** 确认片号连续且全部落盘后认领合并租约，验证类型并生成最终对象，再原子进入 ready。
+     * ready/bound 的重放不重复合并；失败只回退本次 token 仍持有的 completing 状态，允许后续安全恢复。
+     * 返回 ready 后仍需由调用方执行目标业务命令绑定附件，不能把上传成功当作业务保存成功。
+     */
+    complete(id: string, ctx: Ctx): Promise<UploadSession>;
+    /** 标记未绑定会话待删除并使执行 token 失效；实际字节回收交给 cleanup，故返回不表示磁盘已清空。 */
+    cancel(id: string, ctx: Ctx): Promise<{
+        ok: boolean;
+    }>;
+    /** 下载授权：已绑定文件必须仍存在于当前可读业务对象的对应字段；ready 暂存只允许上传者访问。
+     * 每次重新读取对象与范围，隐藏字段/撤权/解绑均可能使文件不可见，不依赖曾经拿到的文件 ID。
+     */
+    private accessible;
+    /** 返回授权后的展示元数据；不创建内容流，下载调用仍须再次检查并可靠审计。 */
+    info(id: string, ctx: Ctx): Promise<FileInfo>;
+    /** 在当前权限下读取完整文件或闭区间，并在交付流之前提交下载审计。
+     * 事务内锁会话再次核对绑定/到期状态，与解绑清理排序；审计失败即拒绝交付，不降级为未审计下载。
+     * 返回的 stream 由 HTTP 层消费；存储读取失败会直接上抛，内容不在数据库事务内传输。
+     */
+    download(id: string, ctx: Ctx, range?: ByteRange): Promise<{
+        info: {
+            id: string;
+            filename: any;
+            bytes: number;
+            contentType: any;
+        };
+        stream: Readable;
+    }>;
+    /** API 后台周期调用；数据库先认领，再在事务外删除。保留墓碑以回收迟到 IO 的残留文件。
+     * 每轮最多处理 limit 个过期会话及 limit 个已完成对象；有效合并/分片租约会推迟删除。
+     * 删除失败保留 deleting 供下轮重试；墓碑一天后重查，已完成对象则只回收其非最终分片。
+     */
+    cleanup(limit?: number): Promise<void>;
+    /** 阻止新 IO，向所有本实例在途操作发出取消并等待收尾；单个取消异常不妨碍等待其他操作。 */
+    close(): Promise<void>;
+}

package/dist/service.js

@@ -0,0 +1,443 @@
+// 上传会话/分片保存在 PostgreSQL；IO 在事务外执行，以 token 和租约阻止迟到结果回写。
+/** 本文件连接业务授权、上传元数据和私有存储，负责 begin → 分片 → complete → ready 的生命周期。
+ * ready 只表示字节已完成，真正绑定由业务命令在自己的事务中完成；服务不直接修改领域对象。
+ * 配额和状态在短数据库事务中决定，长时间 IO 通过续租与 token 栅栏保护，清理保留墓碑兜住迟到写入。
+ */
+import { randomUUID, createHash } from 'node:crypto';
+import { sql } from 'kysely';
+import { z } from 'zod';
+import { fileTypeFromBuffer } from 'file-type';
+import { cageError, isFile } from '@yss123/cage-kernel';
+import { LocalFileStorage } from './local.js';
+/** 创建上传的外部输入：命令/字段定位授权边界，targetId 仅用于修改已有对象。
+ * bytes 为正安全整数字节数；filename 仅作下载展示，禁止路径和控制字符；contentType 后续还会验内容。
+ */
+export const beginUploadSchema = z.object({
+    command: z.string().min(1).max(180), field: z.string().min(1).max(100), targetId: z.string().uuid().optional(),
+    filename: z.string().min(1).max(255).refine(name => !/[\x00-\x1f\x7f/\\]/.test(name), '文件名不能包含路径或控制字符'),
+    bytes: z.number().int().positive().max(Number.MAX_SAFE_INTEGER), contentType: z.string().max(150),
+});
+const SHA = /^[0-9a-f]{64}$/;
+/** IO 租约窗口为两分钟，活动操作每四分之一窗口续租；与完整 IO 总时限分别控制失联和超时。 */
+const LEASE_MS = 120_000;
+/** 将 Zod 的路径化问题统一转换为公开 INVALID_INPUT，避免把 Zod 异常细节直接暴露给 HTTP。 */
+const parse = (schema, raw) => {
+    const result = schema.safeParse(raw);
+    if (!result.success)
+        throw cageError('INVALID_INPUT', result.error.issues.map(i => ({ path: i.path.join('.'), message: i.message })));
+    return result.data;
+};
+/** 文件业务边界的协调器；实例由 API 生命周期管理，close 会取消并等待本实例在途 IO。
+ * 每次访问重新检查当前身份和策略，不把创建会话时的授权当作后续读写的永久许可。
+ */
+export class FileService {
+    kernel;
+    /** 持久字节适配器；名称同时写入会话，防止跨存储空间误读或误清理。 */
+    storage;
+    /** 已通过适配器限制校验的分片字节数，供 HTTP 层设置请求体限制。 */
+    partBytes;
+    /** 服务级文件大小上限，单位字节。 */
+    maxFileBytes;
+    options;
+    active = new Map();
+    closing = false;
+    /** 合并默认策略并做启动期配置校验；不创建上传、不访问存储、不启动定时清理。 */
+    constructor(kernel, options = {}) {
+        this.kernel = kernel;
+        this.storage = options.storage ?? new LocalFileStorage(options.directory);
+        this.options = {
+            partBytes: 16 * 1024 * 1024, maxFileBytes: 2 * 1024 ** 3,
+            maxPendingBytesPerUser: 8 * 1024 ** 3, maxStoredBytesPerTenant: 100 * 1024 ** 3,
+            maxPendingUploadsPerUser: 100, retentionMs: 86400_000, ioTimeoutMs: 1800_000,
+            ...Object.fromEntries(Object.entries(options).filter(([k, v]) => k !== 'storage' && k !== 'directory' && v !== undefined)),
+        };
+        for (const [name, value] of Object.entries(this.options))
+            if (!Number.isSafeInteger(value) || value < 1)
+                throw new Error(`[CAGE-FILE-001] ${name} 必须为正安全整数`);
+        const limits = this.storage.limits;
+        if (this.options.partBytes < limits.minPartBytes || this.options.partBytes > limits.maxPartBytes || Math.ceil(this.options.maxFileBytes / this.options.partBytes) > limits.maxParts)
+            throw new Error('[CAGE-FILE-001] 分片配置超出存储适配器限制');
+        this.partBytes = this.options.partBytes;
+        this.maxFileBytes = this.options.maxFileBytes;
+    }
+    /** 上传/下载入口仅接受具名 user 身份；流程、任务及匿名上下文不能借此占用私有存储。 */
+    identity(ctx) {
+        if (!ctx.userId || ctx.actor?.kind !== 'user')
+            throw cageError('UNAUTHENTICATED');
+    }
+    /** 验证命令能力、文件字段及输入归属；已有对象还要通过当前 read 范围和起始状态检查。
+     * 这里只判断上传资格，最终业务命令仍会独立检查版本、硬约束、不变量和绑定合法性。
+     */
+    async policy(command, field, targetId, ctx) {
+        this.identity(ctx);
+        const registered = this.kernel.registry.command(command), definition = registered?.cmd;
+        if (!registered || !definition?.invokedBy.includes('user') || definition.public)
+            throw cageError('NOT_FOUND');
+        if (!ctx.capabilities.has(command))
+            throw cageError('FORBIDDEN', { capability: command });
+        const f = definition.agg.fields[field];
+        // 上传入口必须明确关联一个能接收该字段的用户命令，不能借只读/无关命令获得暂存空间。
+        if (!f || !isFile(f) || !(definition.input instanceof z.ZodObject) || !Object.hasOwn(definition.input.shape, field))
+            throw cageError('INVALID_INPUT', '目标命令未声明该文件输入字段');
+        if (definition.from === 'new') {
+            if (targetId)
+                throw cageError('INVALID_INPUT', '新建附件会话不能指定已有对象');
+        }
+        else {
+            if (!targetId)
+                throw cageError('INVALID_INPUT', '修改附件需要目标对象 ID');
+            const object = await this.kernel.read.get(definition.agg, targetId, ctx);
+            if (!definition.from.includes(object.status))
+                throw cageError('INVALID_TRANSITION');
+        }
+        return f;
+    }
+    /** 取得当前租户当前上传者的会话，并重新校验业务策略；不存在或存储不匹配统一隐藏为 NOT_FOUND。 */
+    async owned(id, ctx) {
+        this.identity(ctx);
+        parse(z.string().uuid(), id);
+        const row = await this.kernel.app.selectFrom('sys.file_upload').selectAll().where('id', '=', id).where('tenant_id', '=', ctx.tenantId).where('user_id', '=', ctx.userId).executeTakeFirst();
+        if (!row || row.storage !== this.storage.name)
+            throw cageError('NOT_FOUND');
+        await this.policy(row.command_name, row.field_name, row.target_id, ctx);
+        return row;
+    }
+    /** 在调用方事务中锁会话行，串行化修改、完成和取消；调用方应已用 owned/policy 完成授权。 */
+    async locked(tx, id, ctx) {
+        const row = await tx.selectFrom('sys.file_upload').selectAll().where('id', '=', id).where('tenant_id', '=', ctx.tenantId).where('user_id', '=', ctx.userId).forUpdate().executeTakeFirst();
+        if (!row || row.storage !== this.storage.name)
+            throw cageError('NOT_FOUND');
+        return row;
+    }
+    /** 可修改性检查与授权分离；过期、已绑定或进入删除阶段的会话不允许迟到写入重新激活。 */
+    usable(row) {
+        if (new Date(row.expires_at) <= new Date() || ['deleting', 'deleted', 'bound'].includes(row.status))
+            throw cageError('CONFLICT', '上传会话已过期或不可修改');
+    }
+    /** 将数据库 bigint/日期与内部状态投影成公开 DTO，只列出确实已有存储键的已确认分片。 */
+    view(row, parts) {
+        return { id: row.id, aggregate: row.aggregate_name, field: row.field_name, command: row.command_name, targetId: row.target_id,
+            filename: row.filename, bytes: Number(row.bytes), contentType: row.content_type, status: row.status,
+            partBytes: row.part_bytes, partCount: row.part_count, expiresAt: new Date(row.expires_at).toISOString(),
+            parts: parts.filter(p => p.storage_key).map(p => ({ number: p.number, bytes: p.bytes, sha256: p.sha256 })) };
+    }
+    /** 按片号返回内部元数据；仅供已完成所有权检查的调用使用，不能直接作为公开查询入口。 */
+    parts(id) { return this.kernel.app.selectFrom('sys.file_part').selectAll().where('upload_id', '=', id).orderBy('number').execute(); }
+    /** 创建或重放同一次上传申请。租户咨询锁让多实例在同一短事务内核对并占用配额。
+     * 相同用户的同一幂等键只能对应相同规范请求和存储；超配额抛 RATE_LIMITED，不产生半成品会话。
+     * 此步骤只预留元数据与额度，客户端之后使用返回的 partBytes/partCount 上传字节。
+     */
+    async begin(raw, ctx, idempotencyKey) {
+        if (this.closing)
+            throw cageError('CONFLICT', '文件服务正在停止');
+        const request = parse(beginUploadSchema, raw);
+        parse(z.string().min(1).max(200), idempotencyKey);
+        const field = await this.policy(request.command, request.field, request.targetId ?? null, ctx);
+        if (request.bytes > Math.min(field.filePolicy.maxBytes, this.maxFileBytes) || !field.filePolicy.accept.includes(request.contentType))
+            throw cageError('INVALID_INPUT', '文件大小或类型不符合字段限制');
+        const hash = createHash('sha256').update(JSON.stringify(request)).digest('hex');
+        const row = await this.kernel.app.transaction().execute(async (tx) => {
+            // 所有实例共用租户配额锁；只锁短元数据事务，不持有数据库事务传输字节。
+            await sql `select pg_advisory_xact_lock(hashtextextended(${`cage:files:${ctx.tenantId}`}, 0))`.execute(tx);
+            const existing = await tx.selectFrom('sys.file_upload').selectAll().where('tenant_id', '=', ctx.tenantId).where('user_id', '=', ctx.userId).where('idempotency_key', '=', idempotencyKey).executeTakeFirst();
+            if (existing) {
+                if (existing.request_hash !== hash || existing.storage !== this.storage.name)
+                    throw cageError('CONFLICT', '幂等键已用于其他上传');
+                return existing;
+            }
+            const quota = await sql `select coalesce(sum(bytes),0) as total,
+        coalesce(sum(bytes) filter (where user_id = ${ctx.userId}::uuid and status <> 'bound'),0) as pending,
+        count(*) filter (where user_id = ${ctx.userId}::uuid and status <> 'bound') as count
+        from sys.file_upload where tenant_id = ${ctx.tenantId}::uuid and status <> 'deleted'`.execute(tx);
+            const usage = quota.rows[0];
+            if (Number(usage.total) + request.bytes > this.options.maxStoredBytesPerTenant || Number(usage.pending) + request.bytes > this.options.maxPendingBytesPerUser || Number(usage.count) >= this.options.maxPendingUploadsPerUser)
+                throw cageError('RATE_LIMITED', '文件存储或临时上传配额已满');
+            return tx.insertInto('sys.file_upload').values({ id: randomUUID(), tenant_id: ctx.tenantId, user_id: ctx.userId,
+                aggregate_name: this.kernel.registry.command(request.command).cmd.agg.name, field_name: request.field, command_name: request.command,
+                target_id: request.targetId ?? null, filename: request.filename, content_type: request.contentType, bytes: request.bytes,
+                part_bytes: this.partBytes, part_count: Math.ceil(request.bytes / this.partBytes), storage: this.storage.name, status: 'uploading',
+                expires_at: new Date(Date.now() + this.options.retentionMs), idempotency_key: idempotencyKey, request_hash: hash }).returningAll().executeTakeFirstOrThrow();
+        });
+        return this.view(row, await this.parts(row.id));
+    }
+    /** 断点恢复的权威进度查询；返回服务端已确认片清单，客户端不能凭本地发送进度认定上传成功。 */
+    async get(id, ctx) { return this.view(await this.owned(id, ctx), await this.parts(id)); }
+    /** 查询同一业务入口下本人未过期的可恢复会话，最多一百条；摘要不携带完整分片表。 */
+    async list(command, field, targetId, ctx) {
+        await this.policy(command, field, targetId, ctx);
+        let query = this.kernel.app.selectFrom('sys.file_upload').selectAll().where('tenant_id', '=', ctx.tenantId).where('user_id', '=', ctx.userId)
+            .where('command_name', '=', command).where('field_name', '=', field).where('storage', '=', this.storage.name).where('status', 'in', ['uploading', 'completing', 'ready']).where('expires_at', '>', new Date());
+        query = targetId ? query.where('target_id', '=', targetId) : query.where('target_id', 'is', null);
+        const rows = await query.orderBy('created_at', 'desc').limit(100).execute();
+        // 列表只给会话摘要；恢复时 get 取得服务端确认的分片清单。
+        return rows.map(row => this.view(row, []));
+    }
+    /** 为事务外 IO 管理续租、总时限与停机取消。
+     * 续租丢失或数据库异常即中止信号；run 必须在提交元数据前再次检查信号和 token，避免迟到完成覆盖新执行者。
+     * active 持有 Promise 直到 finally，用于 close 等待真正停止，而非仅发出取消请求。
+     */
+    lease(renew, run) {
+        if (this.closing)
+            return Promise.reject(cageError('CONFLICT', '文件服务正在停止'));
+        const controller = new AbortController();
+        let renewing = false;
+        const timer = setInterval(async () => {
+            if (renewing)
+                return;
+            renewing = true;
+            try {
+                if (!await renew())
+                    controller.abort();
+            }
+            catch {
+                controller.abort();
+            }
+            finally {
+                renewing = false;
+            }
+        }, LEASE_MS / 4);
+        const timeout = setTimeout(() => controller.abort(), this.options.ioTimeoutMs);
+        const result = Promise.resolve().then(() => run(controller.signal)).finally(() => { clearInterval(timer); clearTimeout(timeout); this.active.delete(controller); });
+        this.active.set(controller, result);
+        return result;
+    }
+    /** 上传一片：先锁会话认领片号，再释放事务写存储，最后凭 token 确认结果。
+     * 相同片号和摘要的已完成请求可重放；内容变化或有效租约冲突会拒绝。尾片长度从总大小计算。
+     * IO 失败会销毁输入流并释放属于本 token 的租约，已被其他执行接管的记录保持不动。
+     */
+    async putPart(id, number, sha256, source, ctx) {
+        await this.owned(id, ctx);
+        if (!SHA.test(sha256) || !Number.isInteger(number) || number < 1)
+            throw cageError('INVALID_INPUT', '分片编号或 SHA-256 非法');
+        const token = randomUUID();
+        const claim = await this.kernel.app.transaction().execute(async (tx) => {
+            const row = await this.locked(tx, id, ctx);
+            this.usable(row);
+            if (row.status !== 'uploading' || number > row.part_count)
+                throw cageError('CONFLICT', '会话不能接收该分片');
+            const bytes = number === row.part_count ? Number(row.bytes) - (number - 1) * row.part_bytes : row.part_bytes;
+            const old = await tx.selectFrom('sys.file_part').selectAll().where('upload_id', '=', id).where('number', '=', number).executeTakeFirst();
+            if (old?.storage_key) {
+                if (old.sha256 !== sha256)
+                    throw cageError('CONFLICT', '相同片号的内容不一致');
+                return { bytes, replay: true };
+            }
+            if (old?.lease_until && new Date(old.lease_until) > new Date())
+                throw cageError('CONFLICT', '分片正在上传');
+            await tx.insertInto('sys.file_part').values({ upload_id: id, number, bytes, sha256, token, lease_until: new Date(Date.now() + LEASE_MS) })
+                .onConflict(oc => oc.columns(['upload_id', 'number']).doUpdateSet({ bytes, sha256, token, storage_key: null, lease_until: new Date(Date.now() + LEASE_MS) })).execute();
+            return { bytes, replay: false };
+        });
+        if (claim.replay) {
+            source.resume();
+            return { number, bytes: claim.bytes, sha256 };
+        }
+        try {
+            return await this.lease(async () => {
+                const updated = await this.kernel.app.updateTable('sys.file_part').set({ lease_until: new Date(Date.now() + LEASE_MS) }).where('upload_id', '=', id).where('number', '=', number).where('token', '=', token).where('storage_key', 'is', null).executeTakeFirst();
+                return Number(updated.numUpdatedRows) === 1;
+            }, async (signal) => {
+                const key = await this.storage.writePart(id, token, source, { bytes: claim.bytes, sha256, signal });
+                signal.throwIfAborted();
+                await this.kernel.app.transaction().execute(async (tx) => {
+                    const row = await this.locked(tx, id, ctx);
+                    this.usable(row);
+                    if (row.status !== 'uploading')
+                        throw cageError('CONFLICT');
+                    const updated = await tx.updateTable('sys.file_part').set({ storage_key: key, lease_until: null }).where('upload_id', '=', id).where('number', '=', number).where('token', '=', token).executeTakeFirst();
+                    if (Number(updated.numUpdatedRows) !== 1)
+                        throw cageError('CONFLICT', '分片执行租约已失效');
+                });
+                return { number, bytes: claim.bytes, sha256 };
+            });
+        }
+        catch (e) {
+            source.destroy();
+            await this.kernel.app.updateTable('sys.file_part').set({ lease_until: null }).where('upload_id', '=', id).where('number', '=', number).where('token', '=', token).where('storage_key', 'is', null).execute();
+            throw e;
+        }
+    }
+    /** 最多读取首片前 8192 字节检查 MIME；文本仅接受合法 UTF-8 和允许的控制字符。
+     * 这是内容类型核对，不是病毒扫描，也不会验证整个 JSON/CSV 的业务格式。
+     */
+    async verifyType(key, expected) {
+        const stream = await this.storage.read(key, { start: 0, end: 8191 });
+        const buffers = [];
+        try {
+            for await (const chunk of stream)
+                buffers.push(Buffer.from(chunk));
+        }
+        finally {
+            stream.destroy();
+        }
+        const prefix = Buffer.concat(buffers);
+        let detected;
+        try {
+            detected = (await fileTypeFromBuffer(prefix))?.mime;
+        }
+        catch { /* 短文本或截断头由下方保守判断。 */ }
+        if (!detected && ['text/plain', 'text/csv', 'application/json'].includes(expected)) {
+            try {
+                // 前缀末尾可能落在 UTF-8 多字节字符中间，stream 模式不误拒绝合法边界。
+                const text = new TextDecoder('utf-8', { fatal: true }).decode(prefix, { stream: true });
+                if (!/[\x00-\x08\x0b\x0c\x0e-\x1f]/.test(text))
+                    detected = expected;
+            }
+            catch { /* 非 UTF-8 内容不视为文本。 */ }
+        }
+        if ((detected ?? 'application/octet-stream') !== expected)
+            throw cageError('INVALID_INPUT', '文件内容与声明类型不一致');
+    }
+    /** 确认片号连续且全部落盘后认领合并租约，验证类型并生成最终对象，再原子进入 ready。
+     * ready/bound 的重放不重复合并；失败只回退本次 token 仍持有的 completing 状态，允许后续安全恢复。
+     * 返回 ready 后仍需由调用方执行目标业务命令绑定附件，不能把上传成功当作业务保存成功。
+     */
+    async complete(id, ctx) {
+        const owned = await this.owned(id, ctx);
+        // 已绑定后的重试不能重新合并或更改内容。
+        if (owned.status === 'bound')
+            return this.view(owned, []);
+        const token = randomUUID();
+        const claim = await this.kernel.app.transaction().execute(async (tx) => {
+            const row = await this.locked(tx, id, ctx);
+            this.usable(row);
+            if (row.status === 'ready')
+                return { row, parts: [], replay: true };
+            if (row.status === 'completing' && row.lease_until && new Date(row.lease_until) > new Date())
+                throw cageError('CONFLICT', '文件正在校验与合并');
+            const parts = await tx.selectFrom('sys.file_part').selectAll().where('upload_id', '=', id).orderBy('number').execute();
+            if (parts.length !== row.part_count || parts.some((p, i) => p.number !== i + 1 || !p.storage_key))
+                throw cageError('CONFLICT', '分片尚未全部完成');
+            await tx.updateTable('sys.file_upload').set({ status: 'completing', operation_token: token, lease_until: new Date(Date.now() + LEASE_MS) }).where('id', '=', id).execute();
+            return { row, parts, replay: false };
+        });
+        if (claim.replay)
+            return this.view(claim.row, await this.parts(id));
+        try {
+            return await this.lease(async () => {
+                const updated = await this.kernel.app.updateTable('sys.file_upload').set({ lease_until: new Date(Date.now() + LEASE_MS) }).where('id', '=', id).where('status', '=', 'completing').where('operation_token', '=', token).executeTakeFirst();
+                return Number(updated.numUpdatedRows) === 1;
+            }, async (signal) => {
+                const parts = claim.parts.map(p => ({ number: p.number, bytes: p.bytes, sha256: p.sha256, key: p.storage_key }));
+                await this.verifyType(parts[0].key, claim.row.content_type);
+                const key = await this.storage.complete(id, token, parts, { bytes: Number(claim.row.bytes), signal });
+                signal.throwIfAborted();
+                const row = await this.kernel.app.transaction().execute(async (tx) => {
+                    const row = await this.locked(tx, id, ctx);
+                    this.usable(row);
+                    if (row.status !== 'completing' || row.operation_token !== token)
+                        throw cageError('CONFLICT');
+                    return tx.updateTable('sys.file_upload').set({ status: 'ready', storage_key: key, operation_token: null, lease_until: null })
+                        .where('id', '=', id).returningAll().executeTakeFirstOrThrow();
+                });
+                return this.view(row, claim.parts);
+            });
+        }
+        catch (e) {
+            await this.kernel.app.updateTable('sys.file_upload').set({ status: 'uploading', operation_token: null, lease_until: null }).where('id', '=', id).where('status', '=', 'completing').where('operation_token', '=', token).execute();
+            throw e;
+        }
+    }
+    /** 标记未绑定会话待删除并使执行 token 失效；实际字节回收交给 cleanup，故返回不表示磁盘已清空。 */
+    async cancel(id, ctx) {
+        await this.owned(id, ctx);
+        await this.kernel.app.transaction().execute(async (tx) => {
+            const row = await this.locked(tx, id, ctx);
+            if (row.status === 'bound')
+                throw cageError('CONFLICT', '已绑定附件必须通过业务命令移除');
+            await tx.updateTable('sys.file_upload').set({ status: row.status === 'deleted' ? 'deleted' : 'deleting', expires_at: new Date(), operation_token: null }).where('id', '=', id).execute();
+        });
+        return { ok: true };
+    }
+    /** 下载授权：已绑定文件必须仍存在于当前可读业务对象的对应字段；ready 暂存只允许上传者访问。
+     * 每次重新读取对象与范围，隐藏字段/撤权/解绑均可能使文件不可见，不依赖曾经拿到的文件 ID。
+     */
+    async accessible(id, ctx) {
+        this.identity(ctx);
+        parse(z.string().uuid(), id);
+        const row = await this.kernel.app.selectFrom('sys.file_upload').selectAll().where('id', '=', id).where('tenant_id', '=', ctx.tenantId).executeTakeFirst();
+        if (!row || row.storage !== this.storage.name || !row.storage_key)
+            throw cageError('NOT_FOUND');
+        if (row.status === 'bound') {
+            const aggregate = this.kernel.registry.aggregate(row.aggregate_name), field = aggregate?.fields[row.field_name];
+            if (!aggregate || !field || !isFile(field))
+                throw cageError('NOT_FOUND');
+            const object = await this.kernel.read.get(aggregate, row.bound_id, ctx);
+            const value = object[row.field_name];
+            if (!(Array.isArray(value) ? value.includes(id) : value === id))
+                throw cageError('NOT_FOUND');
+        }
+        else {
+            if (row.status !== 'ready' || row.user_id !== ctx.userId || new Date(row.expires_at) <= new Date())
+                throw cageError('NOT_FOUND');
+            await this.policy(row.command_name, row.field_name, row.target_id, ctx);
+        }
+        return row;
+    }
+    /** 返回授权后的展示元数据；不创建内容流，下载调用仍须再次检查并可靠审计。 */
+    async info(id, ctx) {
+        const row = await this.accessible(id, ctx);
+        return { id: row.id, filename: row.filename, bytes: Number(row.bytes), contentType: row.content_type };
+    }
+    /** 在当前权限下读取完整文件或闭区间，并在交付流之前提交下载审计。
+     * 事务内锁会话再次核对绑定/到期状态，与解绑清理排序；审计失败即拒绝交付，不降级为未审计下载。
+     * 返回的 stream 由 HTTP 层消费；存储读取失败会直接上抛，内容不在数据库事务内传输。
+     */
+    async download(id, ctx, range) {
+        const row = await this.accessible(id, ctx), bytes = Number(row.bytes);
+        if (range && (!Number.isSafeInteger(range.start) || !Number.isSafeInteger(range.end) || range.start < 0 || range.end < range.start || range.end >= bytes))
+            throw cageError('INVALID_INPUT', '下载范围非法');
+        await this.kernel.app.transaction().execute(async (tx) => {
+            // 与解绑/清理串行决定是否交付；权限使用当前请求上下文，下载从不携带持久 bearer URL。
+            const current = await tx.selectFrom('sys.file_upload').selectAll().where('id', '=', id).where('tenant_id', '=', ctx.tenantId).forUpdate().executeTakeFirstOrThrow();
+            if (current.status !== row.status || current.bound_id !== row.bound_id || (current.status !== 'bound' && new Date(current.expires_at) <= new Date()))
+                throw cageError('NOT_FOUND');
+            await this.kernel.writeAudit(tx, { tenantId: ctx.tenantId, actor: ctx.actor.id, actorKind: 'user', source: ctx.source,
+                kind: 'read', capability: `${row.aggregate_name}.read`, aggregate: row.aggregate_name, aggregateId: row.bound_id,
+                result: 'ok', diff: { fileId: id, field: row.field_name, operation: 'file.download', ...(range ? { range } : {}) }, requestId: ctx.requestId });
+        });
+        return { info: { id, filename: row.filename, bytes, contentType: row.content_type }, stream: await this.storage.read(row.storage_key, range) };
+    }
+    /** API 后台周期调用；数据库先认领，再在事务外删除。保留墓碑以回收迟到 IO 的残留文件。
+     * 每轮最多处理 limit 个过期会话及 limit 个已完成对象；有效合并/分片租约会推迟删除。
+     * 删除失败保留 deleting 供下轮重试；墓碑一天后重查，已完成对象则只回收其非最终分片。
+     */
+    async cleanup(limit = 100) {
+        const now = new Date();
+        const candidates = await this.kernel.app.selectFrom('sys.file_upload').select('id').where('storage', '=', this.storage.name)
+            .where('status', 'in', ['uploading', 'completing', 'ready', 'deleting', 'deleted']).where('expires_at', '<=', now).orderBy('expires_at').limit(limit).execute();
+        for (const candidate of candidates) {
+            const claimed = await this.kernel.app.transaction().execute(async (tx) => {
+                const row = await tx.selectFrom('sys.file_upload').selectAll().where('id', '=', candidate.id).forUpdate().executeTakeFirstOrThrow();
+                if (row.status === 'bound' || new Date(row.expires_at) > now || (row.lease_until && new Date(row.lease_until) > now))
+                    return false;
+                const inFlight = await tx.selectFrom('sys.file_part').select('number').where('upload_id', '=', row.id).where('lease_until', '>', now).limit(1).executeTakeFirst();
+                if (inFlight)
+                    return false;
+                await tx.updateTable('sys.file_upload').set({ status: 'deleting', operation_token: null }).where('id', '=', row.id).execute();
+                return true;
+            });
+            if (!claimed)
+                continue;
+            await this.storage.remove(candidate.id);
+            // 墓碑每天复查，避免大量旧墓碑占满每一轮待清理队列。
+            await this.kernel.app.updateTable('sys.file_upload').set({ status: 'deleted', storage_key: null, expires_at: new Date(Date.now() + 86400_000) }).where('id', '=', candidate.id).where('status', '=', 'deleting').execute();
+        }
+        const completed = await this.kernel.app.selectFrom('sys.file_upload').select(['id', 'storage_key']).where('storage', '=', this.storage.name).where('status', 'in', ['ready', 'bound']).where('storage_key', 'is not', null)
+            .where(eb => eb.or([eb('pruned_at', 'is', null), eb('pruned_at', '<', new Date(Date.now() - 86400_000))]))
+            .orderBy(sql `pruned_at asc nulls first`).limit(limit).execute();
+        for (const row of completed) {
+            await this.storage.prune(row.id, row.storage_key);
+            await this.kernel.app.updateTable('sys.file_upload').set({ pruned_at: new Date() }).where('id', '=', row.id).execute();
+        }
+    }
+    /** 阻止新 IO，向所有本实例在途操作发出取消并等待收尾；单个取消异常不妨碍等待其他操作。 */
+    async close() {
+        this.closing = true;
+        const work = [...this.active];
+        for (const [controller] of work)
+            controller.abort();
+        await Promise.allSettled(work.map(([, promise]) => promise));
+    }
+}
+//# sourceMappingURL=service.js.map

package/dist/service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.js","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD;;;GAGG;AACH,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAErD,OAAO,EAAE,GAAG,EAAoB,MAAM,QAAQ,CAAC;AAC/C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAAE,SAAS,EAAE,MAAM,EAAwC,MAAM,qBAAqB,CAAC;AAC9F,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAG9C;;GAEG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,QAAQ,EAAE;IAC9G,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,oBAAoB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACvG,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,gBAAgB,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC;CAClG,CAAC,CAAC;AAyCH,MAAM,GAAG,GAAG,gBAAgB,CAAC;AAC7B,qDAAqD;AACrD,MAAM,QAAQ,GAAG,OAAO,CAAC;AACzB,gEAAgE;AAChE,MAAM,KAAK,GAAG,CAAI,MAAoB,EAAE,GAAY,EAAK,EAAE;IACzD,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IACrC,IAAI,CAAC,MAAM,CAAC,OAAO;QAAE,MAAM,SAAS,CAAC,eAAe,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC;IACtI,OAAO,MAAM,CAAC,IAAI,CAAC;AACrB,CAAC,CAAC;AAEF;;GAEG;AACH,MAAM,OAAO,WAAW;IAWD;IAVrB,sCAAsC;IAC7B,OAAO,CAAc;IAC9B,wCAAwC;IAC/B,SAAS,CAAS;IAC3B,sBAAsB;IACb,YAAY,CAAS;IACb,OAAO,CAA8D;IACrE,MAAM,GAAG,IAAI,GAAG,EAAqC,CAAC;IAC/D,OAAO,GAAG,KAAK,CAAC;IACxB,2CAA2C;IAC3C,YAAqB,MAAc,EAAE,UAA8B,EAAE;QAAhD,WAAM,GAAN,MAAM,CAAQ;QACjC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,IAAI,gBAAgB,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAC1E,IAAI,CAAC,OAAO,GAAG;YACb,SAAS,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI,EAAE,YAAY,EAAE,CAAC,GAAG,IAAI,IAAI,CAAC;YACxD,sBAAsB,EAAE,CAAC,GAAG,IAAI,IAAI,CAAC,EAAE,uBAAuB,EAAE,GAAG,GAAG,IAAI,IAAI,CAAC;YAC/E,wBAAwB,EAAE,GAAG,EAAE,WAAW,EAAE,SAAS,EAAE,WAAW,EAAE,QAAQ;YAC5E,GAAG,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,WAAW,IAAI,CAAC,KAAK,SAAS,CAAC,CAAC;SAC3H,CAAC;QACF,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC;YAAE,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC;gBAAE,MAAM,IAAI,KAAK,CAAC,mBAAmB,IAAI,WAAW,CAAC,CAAC;QAC7J,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;QACnC,IAAI,IAAI,CAAC,OAAO,CAAC,SAAS,GAAG,MAAM,CAAC,YAAY,IAAI,IAAI,CAAC,OAAO,CAAC,SAAS,GAAG,MAAM,CAAC,YAAY,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,GAAG,MAAM,CAAC,QAAQ;YACjL,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;QACnD,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC;QAAC,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC;IACzF,CAAC;IAED,kDAAkD;IAC1C,QAAQ,CAAC,GAAQ;QACvB,IAAI,CAAC,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,KAAK,EAAE,IAAI,KAAK,MAAM;YAAE,MAAM,SAAS,CAAC,iBAAiB,CAAC,CAAC;IACpF,CAAC;IACD;;OAEG;IACK,KAAK,CAAC,MAAM,CAAC,OAAe,EAAE,KAAa,EAAE,QAAuB,EAAE,GAAQ;QACpF,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QACnB,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,UAAU,GAAG,UAAU,EAAE,GAAG,CAAC;QACvF,IAAI,CAAC,UAAU,IAAI,CAAC,UAAU,EAAE,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,UAAU,CAAC,MAAM;YAAE,MAAM,SAAS,CAAC,WAAW,CAAC,CAAC;QAC9G,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC;YAAE,MAAM,SAAS,CAAC,WAAW,EAAE,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC,CAAC;QAC1F,MAAM,CAAC,GAAG,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAyB,CAAC;QAC/D,4CAA4C;QAC5C,IAAI,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,UAAU,CAAC,KAAK,YAAY,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC;YAAE,MAAM,SAAS,CAAC,eAAe,EAAE,gBAAgB,CAAC,CAAC;QACxK,IAAI,UAAU,CAAC,IAAI,KAAK,KAAK,EAAE,CAAC;YAC9B,IAAI,QAAQ;gBAAE,MAAM,SAAS,CAAC,eAAe,EAAE,gBAAgB,CAAC,CAAC;QACnE,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,QAAQ;gBAAE,MAAM,SAAS,CAAC,eAAe,EAAE,eAAe,CAAC,CAAC;YACjE,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,CAAC,CAAC;YACzE,IAAI,CAAE,UAAU,CAAC,IAA0B,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC;gBAAE,MAAM,SAAS,CAAC,oBAAoB,CAAC,CAAC;QAC7G,CAAC;QACD,OAAO,CAAC,CAAC;IACX,CAAC;IACD,yDAAyD;IACjD,KAAK,CAAC,KAAK,CAAC,EAAU,EAAE,GAAQ;QACtC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;QACjD,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,iBAAiB,CAAC,CAAC,SAAS,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,WAAW,EAAE,GAAG,EAAE,GAAG,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,SAAS,EAAE,GAAG,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,gBAAgB,EAAE,CAAC;QAC5L,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,OAAO,KAAK,IAAI,CAAC,OAAO,CAAC,IAAI;YAAE,MAAM,SAAS,CAAC,WAAW,CAAC,CAAC;QAC5E,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,YAAY,EAAE,GAAG,CAAC,UAAU,EAAE,GAAG,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;QACxE,OAAO,GAAG,CAAC;IACb,CAAC;IACD,wDAAwD;IAChD,KAAK,CAAC,MAAM,CAAC,EAAoB,EAAE,EAAU,EAAE,GAAQ;QAC7D,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,UAAU,CAAC,iBAAiB,CAAC,CAAC,SAAS,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,WAAW,EAAE,GAAG,EAAE,GAAG,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,SAAS,EAAE,GAAG,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,SAAS,EAAE,CAAC,gBAAgB,EAAE,CAAC;QAC3L,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,OAAO,KAAK,IAAI,CAAC,OAAO,CAAC,IAAI;YAAE,MAAM,SAAS,CAAC,WAAW,CAAC,CAAC;QAC5E,OAAO,GAAG,CAAC;IACb,CAAC;IACD,+CAA+C;IACvC,MAAM,CAAC,GAAQ;QACrB,IAAI,IAAI,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,IAAI,IAAI,EAAE,IAAI,CAAC,UAAU,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC;YAAE,MAAM,SAAS,CAAC,UAAU,EAAE,cAAc,CAAC,CAAC;IACnJ,CAAC;IACD,qDAAqD;IAC7C,IAAI,CAAC,GAAQ,EAAE,KAAY;QACjC,OAAO,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,SAAS,EAAE,GAAG,CAAC,cAAc,EAAE,KAAK,EAAE,GAAG,CAAC,UAAU,EAAE,OAAO,EAAE,GAAG,CAAC,YAAY,EAAE,QAAQ,EAAE,GAAG,CAAC,SAAS;YAC3H,QAAQ,EAAE,GAAG,CAAC,QAAQ,EAAE,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,WAAW,EAAE,GAAG,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM;YACnG,SAAS,EAAE,GAAG,CAAC,UAAU,EAAE,SAAS,EAAE,GAAG,CAAC,UAAU,EAAE,SAAS,EAAE,IAAI,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,WAAW,EAAE;YACvG,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC;IACjH,CAAC;IACD,+CAA+C;IACvC,KAAK,CAAC,EAAU,IAAI,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,eAAe,CAAC,CAAC,SAAS,EAAE,CAAC,KAAK,CAAC,WAAW,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IAErJ;;;OAGG;IACH,KAAK,CAAC,KAAK,CAAC,GAAY,EAAE,GAAQ,EAAE,cAAsB;QACxD,IAAI,IAAI,CAAC,OAAO;YAAE,MAAM,SAAS,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;QAC1D,MAAM,OAAO,GAAG,KAAK,CAAC,iBAAiB,EAAE,GAAG,CAAC,CAAC;QAC9C,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,cAAc,CAAC,CAAC;QAClD,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,QAAQ,IAAI,IAAI,EAAE,GAAG,CAAC,CAAC;QAC/F,IAAI,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,UAAW,CAAC,QAAQ,EAAE,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,UAAW,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,WAAW,CAAC;YAAE,MAAM,SAAS,CAAC,eAAe,EAAE,gBAAgB,CAAC,CAAC;QAC3L,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAChF,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,KAAK,EAAC,EAAE,EAAC,EAAE;YACjE,qCAAqC;YACrC,MAAM,GAAG,CAAA,iDAAiD,cAAc,GAAG,CAAC,QAAQ,EAAE,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;YAC1G,MAAM,QAAQ,GAAG,MAAM,EAAE,CAAC,UAAU,CAAC,iBAAiB,CAAC,CAAC,SAAS,EAAE,CAAC,KAAK,CAAC,WAAW,EAAE,GAAG,EAAE,GAAG,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,SAAS,EAAE,GAAG,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,iBAAiB,EAAE,GAAG,EAAE,cAAc,CAAC,CAAC,gBAAgB,EAAE,CAAC;YAC7M,IAAI,QAAQ,EAAE,CAAC;gBACb,IAAI,QAAQ,CAAC,YAAY,KAAK,IAAI,IAAI,QAAQ,CAAC,OAAO,KAAK,IAAI,CAAC,OAAO,CAAC,IAAI;oBAAE,MAAM,SAAS,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC;gBACxH,OAAO,QAAQ,CAAC;YAClB,CAAC;YACD,MAAM,KAAK,GAAG,MAAM,GAAG,CAAmD;sDAC1B,GAAG,CAAC,MAAM;2CACrB,GAAG,CAAC,MAAM;iDACJ,GAAG,CAAC,QAAQ,gCAAgC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;YACpG,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAC5B,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,uBAAuB,IAAI,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,sBAAsB,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,wBAAwB;gBAC3N,MAAM,SAAS,CAAC,cAAc,EAAE,eAAe,CAAC,CAAC;YACnD,OAAO,EAAE,CAAC,UAAU,CAAC,iBAAiB,CAAC,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,UAAU,EAAE,EAAE,SAAS,EAAE,GAAG,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,CAAC,MAAM;gBAC7G,cAAc,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAE,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,CAAC,OAAO;gBACrI,SAAS,EAAE,OAAO,CAAC,QAAQ,IAAI,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,YAAY,EAAE,OAAO,CAAC,WAAW,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK;gBACxH,UAAU,EAAE,IAAI,CAAC,SAAS,EAAE,UAAU,EAAE,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW;gBAClI,UAAU,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,eAAe,EAAE,cAAc,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC,YAAY,EAAE,CAAC,uBAAuB,EAAE,CAAC;QACjK,CAAC,CAAC,CAAC;QACH,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IAClD,CAAC;IAED,kDAAkD;IAClD,KAAK,CAAC,GAAG,CAAC,EAAU,EAAE,GAAQ,IAA4B,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9H,6CAA6C;IAC7C,KAAK,CAAC,IAAI,CAAC,OAAe,EAAE,KAAa,EAAE,QAAuB,EAAE,GAAQ;QAC1E,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,CAAC,CAAC;QACjD,IAAI,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,iBAAiB,CAAC,CAAC,SAAS,EAAE,CAAC,KAAK,CAAC,WAAW,EAAE,GAAG,EAAE,GAAG,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,SAAS,EAAE,GAAG,EAAE,GAAG,CAAC,MAAM,CAAC;aAC1I,KAAK,CAAC,cAAc,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC,KAAK,CAAC,YAAY,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC,KAAK,CAAC,SAAS,EAAE,GAAG,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,YAAY,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,YAAY,EAAE,GAAG,EAAE,IAAI,IAAI,EAAE,CAAC,CAAC;QACjN,KAAK,GAAG,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,WAAW,EAAE,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,WAAW,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;QAClG,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,OAAO,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,CAAC;QAC5E,iCAAiC;QACjC,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC;IAC7C,CAAC;IAED;;;OAGG;IACK,KAAK,CAAI,KAA6B,EAAE,GAAwC;QACtF,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC;QAC3E,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,IAAI,QAAQ,GAAG,KAAK,CAAC;QACrB,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,IAAI,EAAE;YACnC,IAAI,QAAQ;gBAAE,OAAO;YACrB,QAAQ,GAAG,IAAI,CAAC;YAChB,IAAI,CAAC;gBAAC,IAAI,CAAC,MAAM,KAAK,EAAE;oBAAE,UAAU,CAAC,KAAK,EAAE,CAAC;YAAC,CAAC;YAAC,MAAM,CAAC;gBAAC,UAAU,CAAC,KAAK,EAAE,CAAC;YAAC,CAAC;oBAAS,CAAC;gBAAC,QAAQ,GAAG,KAAK,CAAC;YAAC,CAAC;QAC7G,CAAC,EAAE,QAAQ,GAAG,CAAC,CAAC,CAAC;QACjB,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;QAC/E,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACpK,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;QACpC,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,OAAO,CAAC,EAAU,EAAE,MAAc,EAAE,MAAc,EAAE,MAAgB,EAAE,GAAQ;QAClF,MAAM,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;QAC1B,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC;YAAE,MAAM,SAAS,CAAC,eAAe,EAAE,kBAAkB,CAAC,CAAC;QACvH,MAAM,KAAK,GAAG,UAAU,EAAE,CAAC;QAC3B,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,KAAK,EAAC,EAAE,EAAC,EAAE;YACnE,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC;YAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC7D,IAAI,GAAG,CAAC,MAAM,KAAK,WAAW,IAAI,MAAM,GAAG,GAAG,CAAC,UAAU;gBAAE,MAAM,SAAS,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC;YACpG,MAAM,KAAK,GAAG,MAAM,KAAK,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC;YAC7G,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,UAAU,CAAC,eAAe,CAAC,CAAC,SAAS,EAAE,CAAC,KAAK,CAAC,WAAW,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,QAAQ,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC,gBAAgB,EAAE,CAAC;YACzI,IAAI,GAAG,EAAE,WAAW,EAAE,CAAC;gBACrB,IAAI,GAAG,CAAC,MAAM,KAAK,MAAM;oBAAE,MAAM,SAAS,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC;gBACrE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;YACjC,CAAC;YACD,IAAI,GAAG,EAAE,WAAW,IAAI,IAAI,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,GAAG,IAAI,IAAI,EAAE;gBAAE,MAAM,SAAS,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;YACtG,MAAM,EAAE,CAAC,UAAU,CAAC,eAAe,CAAC,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,CAAC,EAAE,CAAC;iBACvI,UAAU,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;YAC1K,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;QAClC,CAAC,CAAC,CAAC;QACH,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;YAAC,MAAM,CAAC,MAAM,EAAE,CAAC;YAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC;QAAC,CAAC;QACrF,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,IAAI,EAAE;gBACjC,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,WAAW,CAAC,eAAe,CAAC,CAAC,GAAG,CAAC,EAAE,WAAW,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,WAAW,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,QAAQ,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC,KAAK,CAAC,OAAO,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC,KAAK,CAAC,aAAa,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,gBAAgB,EAAE,CAAC;gBACjQ,OAAO,MAAM,CAAC,OAAO,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;YAC9C,CAAC,EAAE,KAAK,EAAC,MAAM,EAAC,EAAE;gBAChB,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;gBACpG,MAAM,CAAC,cAAc,EAAE,CAAC;gBACxB,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,KAAK,EAAC,EAAE,EAAC,EAAE;oBACrD,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC;oBAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;oBAC7D,IAAI,GAAG,CAAC,MAAM,KAAK,WAAW;wBAAE,MAAM,SAAS,CAAC,UAAU,CAAC,CAAC;oBAC5D,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,WAAW,CAAC,eAAe,CAAC,CAAC,GAAG,CAAC,EAAE,WAAW,EAAE,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,WAAW,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,QAAQ,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC,KAAK,CAAC,OAAO,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC,gBAAgB,EAAE,CAAC;oBAC1M,IAAI,MAAM,CAAC,OAAO,CAAC,cAAc,CAAC,KAAK,CAAC;wBAAE,MAAM,SAAS,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC;gBACrF,CAAC,CAAC,CAAC;gBACH,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC;YAChD,CAAC,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,CAAC,OAAO,EAAE,CAAC;YACjB,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,WAAW,CAAC,eAAe,CAAC,CAAC,GAAG,CAAC,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,WAAW,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,QAAQ,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC,KAAK,CAAC,OAAO,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC,KAAK,CAAC,aAAa,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC;YAC7M,MAAM,CAAC,CAAC;QACV,CAAC;IACH,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,UAAU,CAAC,GAAW,EAAE,QAAgB;QACpD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC;QACrE,MAAM,OAAO,GAAa,EAAE,CAAC;QAC7B,IAAI,CAAC;YAAC,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,MAAM;gBAAE,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;QAAC,CAAC;gBAAS,CAAC;YAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QAAC,CAAC;QACzG,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACtC,IAAI,QAA4B,CAAC;QACjC,IAAI,CAAC;YAAC,QAAQ,GAAG,CAAC,MAAM,kBAAkB,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC,CAAC,qBAAqB,CAAC,CAAC;QAC5F,IAAI,CAAC,QAAQ,IAAI,CAAC,YAAY,EAAE,UAAU,EAAE,kBAAkB,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;YACnF,IAAI,CAAC;gBACH,4CAA4C;gBAC5C,MAAM,IAAI,GAAG,IAAI,WAAW,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;gBACxF,IAAI,CAAC,8BAA8B,CAAC,IAAI,CAAC,IAAI,CAAC;oBAAE,QAAQ,GAAG,QAAQ,CAAC;YACtE,CAAC;YAAC,MAAM,CAAC,CAAC,sBAAsB,CAAC,CAAC;QACpC,CAAC;QACD,IAAI,CAAC,QAAQ,IAAI,0BAA0B,CAAC,KAAK,QAAQ;YAAE,MAAM,SAAS,CAAC,eAAe,EAAE,cAAc,CAAC,CAAC;IAC9G,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,QAAQ,CAAC,EAAU,EAAE,GAAQ;QACjC,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;QACxC,sBAAsB;QACtB,IAAI,KAAK,CAAC,MAAM,KAAK,OAAO;YAAE,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAC1D,MAAM,KAAK,GAAG,UAAU,EAAE,CAAC;QAC3B,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,KAAK,EAAC,EAAE,EAAC,EAAE;YACnE,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC;YAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC7D,IAAI,GAAG,CAAC,MAAM,KAAK,OAAO;gBAAE,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,EAAW,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;YAC7E,IAAI,GAAG,CAAC,MAAM,KAAK,YAAY,IAAI,GAAG,CAAC,WAAW,IAAI,IAAI,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,GAAG,IAAI,IAAI,EAAE;gBAAE,MAAM,SAAS,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC;YACvI,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC,UAAU,CAAC,eAAe,CAAC,CAAC,SAAS,EAAE,CAAC,KAAK,CAAC,WAAW,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,EAAE,CAAC;YACvH,IAAI,KAAK,CAAC,MAAM,KAAK,GAAG,CAAC,UAAU,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC;gBAAE,MAAM,SAAS,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;YAC3I,MAAM,EAAE,CAAC,WAAW,CAAC,iBAAiB,CAAC,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,YAAY,EAAE,eAAe,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;YAC3K,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;QACvC,CAAC,CAAC,CAAC;QACH,IAAI,KAAK,CAAC,MAAM;YAAE,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,MAAM,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC;QACpE,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,IAAI,EAAE;gBACjC,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,WAAW,CAAC,iBAAiB,CAAC,CAAC,GAAG,CAAC,EAAE,WAAW,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,QAAQ,EAAE,GAAG,EAAE,YAAY,CAAC,CAAC,KAAK,CAAC,iBAAiB,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC,gBAAgB,EAAE,CAAC;gBAC3O,OAAO,MAAM,CAAC,OAAO,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;YAC9C,CAAC,EAAE,KAAK,EAAC,MAAM,EAAC,EAAE;gBAChB,MAAM,KAAK,GAAiB,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;gBAC/H,MAAM,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;gBAC5D,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;gBACtG,MAAM,CAAC,cAAc,EAAE,CAAC;gBACxB,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,KAAK,EAAC,EAAE,EAAC,EAAE;oBACjE,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC;oBAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;oBAC7D,IAAI,GAAG,CAAC,MAAM,KAAK,YAAY,IAAI,GAAG,CAAC,eAAe,KAAK,KAAK;wBAAE,MAAM,SAAS,CAAC,UAAU,CAAC,CAAC;oBAC9F,OAAO,EAAE,CAAC,WAAW,CAAC,iBAAiB,CAAC,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,GAAG,EAAE,eAAe,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;yBAC1H,KAAK,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,YAAY,EAAE,CAAC,uBAAuB,EAAE,CAAC;gBACnE,CAAC,CAAC,CAAC;gBACH,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;YACrC,CAAC,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,WAAW,CAAC,iBAAiB,CAAC,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,eAAe,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,QAAQ,EAAE,GAAG,EAAE,YAAY,CAAC,CAAC,KAAK,CAAC,iBAAiB,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;YACnO,MAAM,CAAC,CAAC;QACV,CAAC;IACH,CAAC;IAED,4DAA4D;IAC5D,KAAK,CAAC,MAAM,CAAC,EAAU,EAAE,GAAQ;QAC/B,MAAM,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;QAC1B,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,KAAK,EAAC,EAAE,EAAC,EAAE;YACrD,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC;YAC3C,IAAI,GAAG,CAAC,MAAM,KAAK,OAAO;gBAAE,MAAM,SAAS,CAAC,UAAU,EAAE,iBAAiB,CAAC,CAAC;YAC3E,MAAM,EAAE,CAAC,WAAW,CAAC,iBAAiB,CAAC,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,EAAE,UAAU,EAAE,IAAI,IAAI,EAAE,EAAE,eAAe,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;QAC3L,CAAC,CAAC,CAAC;QACH,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;IACtB,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,UAAU,CAAC,EAAU,EAAE,GAAQ;QAC3C,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;QACjD,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,iBAAiB,CAAC,CAAC,SAAS,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,WAAW,EAAE,GAAG,EAAE,GAAG,CAAC,QAAQ,CAAC,CAAC,gBAAgB,EAAE,CAAC;QAC1J,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,OAAO,KAAK,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,WAAW;YAAE,MAAM,SAAS,CAAC,WAAW,CAAC,CAAC;QAChG,IAAI,GAAG,CAAC,MAAM,KAAK,OAAO,EAAE,CAAC;YAC3B,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,GAAG,CAAC,cAAc,CAAC,EAAE,KAAK,GAAG,SAAS,EAAE,MAAM,CAAC,GAAG,CAAC,UAAU,CAAyB,CAAC;YACxI,IAAI,CAAC,SAAS,IAAI,CAAC,KAAK,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC;gBAAE,MAAM,SAAS,CAAC,WAAW,CAAC,CAAC;YACzE,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;YACxE,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;YACrC,IAAI,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,KAAK,EAAE,CAAC;gBAAE,MAAM,SAAS,CAAC,WAAW,CAAC,CAAC;QAChG,CAAC;aAAM,CAAC;YACN,IAAI,GAAG,CAAC,MAAM,KAAK,OAAO,IAAI,GAAG,CAAC,OAAO,KAAK,GAAG,CAAC,MAAM,IAAI,IAAI,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,IAAI,IAAI,EAAE;gBAAE,MAAM,SAAS,CAAC,WAAW,CAAC,CAAC;YACjI,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,YAAY,EAAE,GAAG,CAAC,UAAU,EAAE,GAAG,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;QAC1E,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IACD,0CAA0C;IAC1C,KAAK,CAAC,IAAI,CAAC,EAAU,EAAE,GAAQ;QAC7B,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;QAC3C,OAAO,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,QAAQ,EAAE,GAAG,CAAC,QAAQ,EAAE,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,WAAW,EAAE,GAAG,CAAC,YAAY,EAAE,CAAC;IACzG,CAAC;IACD;;;OAGG;IACH,KAAK,CAAC,QAAQ,CAAC,EAAU,EAAE,GAAQ,EAAE,KAAiB;QACpD,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,EAAE,EAAE,GAAG,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACtE,IAAI,KAAK,IAAI,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,KAAK,GAAG,CAAC,IAAI,KAAK,CAAC,GAAG,GAAG,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,GAAG,IAAI,KAAK,CAAC;YAAE,MAAM,SAAS,CAAC,eAAe,EAAE,QAAQ,CAAC,CAAC;QACtM,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,KAAK,EAAC,EAAE,EAAC,EAAE;YACrD,kDAAkD;YAClD,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,UAAU,CAAC,iBAAiB,CAAC,CAAC,SAAS,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,WAAW,EAAE,GAAG,EAAE,GAAG,CAAC,QAAQ,CAAC,CAAC,SAAS,EAAE,CAAC,uBAAuB,EAAE,CAAC;YACpK,IAAI,OAAO,CAAC,MAAM,KAAK,GAAG,CAAC,MAAM,IAAI,OAAO,CAAC,QAAQ,KAAK,GAAG,CAAC,QAAQ,IAAI,CAAC,OAAO,CAAC,MAAM,KAAK,OAAO,IAAI,IAAI,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,IAAI,IAAI,EAAE,CAAC;gBAAE,MAAM,SAAS,CAAC,WAAW,CAAC,CAAC;YACnL,MAAM,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,GAAG,CAAC,QAAQ,EAAE,KAAK,EAAE,GAAG,CAAC,KAAM,CAAC,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM;gBACpH,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,GAAG,CAAC,cAAc,OAAO,EAAE,SAAS,EAAE,GAAG,CAAC,cAAc,EAAE,WAAW,EAAE,GAAG,CAAC,QAAQ;gBAChH,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,CAAC,UAAU,EAAE,SAAS,EAAE,eAAe,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC;QACpJ,CAAC,CAAC,CAAC;QACH,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE,QAAQ,EAAE,GAAG,CAAC,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,CAAC,YAAY,EAAE,EAAE,MAAM,EAAE,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,KAAK,CAAC,EAAE,CAAC;IACjJ,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,OAAO,CAAC,KAAK,GAAG,GAAG;QACvB,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,iBAAiB,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,SAAS,EAAE,GAAG,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;aACzH,KAAK,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,YAAY,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,YAAY,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;QAClK,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;YACnC,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,KAAK,EAAC,EAAE,EAAC,EAAE;gBACrE,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,UAAU,CAAC,iBAAiB,CAAC,CAAC,SAAS,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,EAAE,SAAS,CAAC,EAAE,CAAC,CAAC,SAAS,EAAE,CAAC,uBAAuB,EAAE,CAAC;gBACpI,IAAI,GAAG,CAAC,MAAM,KAAK,OAAO,IAAI,IAAI,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,WAAW,IAAI,IAAI,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,GAAG,GAAG,CAAC;oBAAE,OAAO,KAAK,CAAC;gBACnI,MAAM,QAAQ,GAAG,MAAM,EAAE,CAAC,UAAU,CAAC,eAAe,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,WAAW,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,aAAa,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,gBAAgB,EAAE,CAAC;gBAClK,IAAI,QAAQ;oBAAE,OAAO,KAAK,CAAC;gBAC3B,MAAM,EAAE,CAAC,WAAW,CAAC,iBAAiB,CAAC,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,eAAe,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;gBAC9H,OAAO,IAAI,CAAC;YACd,CAAC,CAAC,CAAC;YACH,IAAI,CAAC,OAAO;gBAAE,SAAS;YACvB,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;YACxC,4BAA4B;YAC5B,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,WAAW,CAAC,iBAAiB,CAAC,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,EAAE,SAAS,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,QAAQ,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC,OAAO,EAAE,CAAC;QAC7N,CAAC;QACD,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,EAAE,GAAG,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,aAAa,EAAE,QAAQ,EAAE,IAAI,CAAC;aACxN,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,WAAW,EAAE,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,WAAW,EAAE,GAAG,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;aACzG,OAAO,CAAC,GAAG,CAAA,2BAA2B,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;QAClE,KAAK,MAAM,GAAG,IAAI,SAAS,EAAE,CAAC;YAC5B,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,WAAW,CAAC,CAAC;YAClD,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,WAAW,CAAC,iBAAiB,CAAC,CAAC,GAAG,CAAC,EAAE,SAAS,EAAE,IAAI,IAAI,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;QACzH,CAAC;IACH,CAAC;IAED,kDAAkD;IAClD,KAAK,CAAC,KAAK;QACT,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,MAAM,IAAI,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;QAC9B,KAAK,MAAM,CAAC,UAAU,CAAC,IAAI,IAAI;YAAE,UAAU,CAAC,KAAK,EAAE,CAAC;QACpD,MAAM,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;IAC/D,CAAC;CACF"}

package/dist/storage.d.ts

@@ -0,0 +1,46 @@
+import type { Readable } from 'node:stream';
+/** 已由元数据层确认的分片。number 从 1 开始；bytes 是精确字节数；sha256 为小写十六进制摘要。
+ * key 是适配器返回的不透明位置，不向浏览器暴露，也不承担业务授权职责。
+ */
+export interface StoredPart {
+    number: number;
+    key: string;
+    bytes: number;
+    sha256: string;
+}
+/** 下载的闭区间，两端都包含在返回内容中；合法性由 FileService 按文件总长度检查。 */
+export interface ByteRange {
+    start: number;
+    end: number;
+}
+/** 私有字节存储协议，由 FileService 在数据库事务外调用。
+ * 适配器负责内容完整性、流式 IO 和取消；会话所有权、配额、租约与业务绑定由上层处理。
+ * 写入返回的 key 必须在进程重启后仍可读取；失败不得让其他执行 token 的内容失效。
+ */
+export interface FileStorage {
+    /** 持久标识；重启后必须指向同一存储空间。 */
+    readonly name: string;
+    /** 分片最小/最大字节数及每文件最大分片数；服务启动时据此拒绝不兼容配置。 */
+    readonly limits: {
+        minPartBytes: number;
+        maxPartBytes: number;
+        maxParts: number;
+    };
+    /** 所有操作都必须可重试；token 隔离过期执行者，不能覆盖其他 token 的产物。 */
+    writePart(upload: string, token: string, source: Readable, options: {
+        bytes: number;
+        sha256: string;
+        signal: AbortSignal;
+    }): Promise<string>;
+    /** 按调用方给出的顺序合并已确认分片；bytes 是最终总长度，signal 失效后不得报告成功。 */
+    complete(upload: string, token: string, parts: readonly StoredPart[], options: {
+        bytes: number;
+        signal: AbortSignal;
+    }): Promise<string>;
+    /** 返回可读流而非完整 Buffer；调用方负责消费或销毁流，适配器不得公开持久访问 URL。 */
+    read(key: string, range?: ByteRange): Promise<Readable>;
+    /** 删除该上传下的分片及最终内容；没有内容也应成功。 */
+    remove(upload: string): Promise<void>;
+    /** 完成后的分片回收，不删除最终内容；失败时后续周期重试。 */
+    prune(upload: string, keepKey: string): Promise<void>;
+}

package/dist/storage.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=storage.js.map

package/dist/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@yss123/cage-files",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.3.1",
+  "description": "Cage 私有文件与可恢复分片上传：本地存储及对象存储适配接口",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "kysely": "^0.28.5",
+    "zod": "^4.1.5",
+    "file-type": "^21.0.0",
+    "@yss123/cage-kernel": "0.3.1"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shunshunyue/cage.git",
+    "directory": "packages/files"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
 }