@remnic/core 1.1.31 → 9.3.515

package/dist/chunk-UWY7GIVS.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/network/webdav.ts"],"sourcesContent":["import { constants } from \"node:fs\";\nimport type { FileHandle } from \"node:fs/promises\";\nimport { mkdir, open, readdir, realpath, stat } from \"node:fs/promises\";\nimport { createServer, type IncomingMessage, type Server, type ServerResponse } from \"node:http\";\nimport { timingSafeEqual } from \"node:crypto\";\nimport path from \"node:path\";\nimport { pipeline } from \"node:stream/promises\";\nimport { URL } from \"node:url\";\n\nexport function hostToUrlAuthority(host: string): string {\n  if (host.includes(\":\") && !host.startsWith(\"[\") && !host.endsWith(\"]\")) {\n    return `[${host}]`;\n  }\n  return host;\n}\n\nexport interface WebDavAuth {\n  username: string;\n  password: string;\n}\n\nexport interface WebDavServerOptions {\n  enabled?: boolean;\n  host?: string;\n  port: number;\n  allowlistDirs: string[];\n  auth?: WebDavAuth;\n}\n\nexport interface WebDavServerStatus {\n  running: boolean;\n  host: string;\n  port: number;\n  rootCount: number;\n}\n\ninterface AllowedRoot {\n  absolute: string;\n  name: string;\n}\n\ntype WebDavReadOpenResult =\n  | { ok: true; handle: FileHandle; size: number }\n  | { ok: false; code: number; message: string };\n\nfunction validateWebDavAuth(auth: WebDavAuth): WebDavAuth {\n  if (typeof auth.username !== \"string\" || auth.username.trim().length === 0) {\n    throw new Error(\"webdav auth.username must be a non-empty string\");\n  }\n  if (typeof auth.password !== \"string\" || auth.password.trim().length === 0) {\n    throw new Error(\"webdav auth.password must be a non-empty string\");\n  }\n  return auth;\n}\n\nexport async function openWebDavFileForRead(absolutePath: string): Promise<WebDavReadOpenResult> {\n  let handle: FileHandle | null = null;\n  try {\n    handle = await open(absolutePath, constants.O_RDONLY | constants.O_NOFOLLOW);\n    const info = await handle.stat();\n    if (!info.isFile()) {\n      await handle.close().catch(() => {});\n      return { ok: false, code: 403, message: \"path is not a file\" };\n    }\n    return { ok: true, handle, size: info.size };\n  } catch (err) {\n    await handle?.close().catch(() => {});\n    const code = (err as NodeJS.ErrnoException).code;\n    if (code === \"ELOOP\") {\n      return { ok: false, code: 403, message: \"path escaped allowlist via symlink\" };\n    }\n    if (code === \"ENOENT\" || code === \"ENOTDIR\") {\n      return { ok: false, code: 404, message: \"not found\" };\n    }\n    return { ok: false, code: 404, message: \"not found\" };\n  }\n}\n\nexport class WebDavServer {\n  private readonly options: Required<Omit<WebDavServerOptions, \"auth\">> & Pick<WebDavServerOptions, \"auth\">;\n  private readonly allowedRoots: AllowedRoot[];\n  private server: Server | null = null;\n  private startPromise: Promise<WebDavServerStatus> | null = null;\n  private listening = false;\n  private boundPort: number;\n\n  private constructor(\n    options: Required<Omit<WebDavServerOptions, \"auth\">> & Pick<WebDavServerOptions, \"auth\">,\n    allowedRoots: AllowedRoot[],\n  ) {\n    this.options = options;\n    this.allowedRoots = allowedRoots;\n    this.boundPort = options.port;\n  }\n\n  static async create(input: WebDavServerOptions): Promise<WebDavServer> {\n    const options: Required<Omit<WebDavServerOptions, \"auth\">> & Pick<WebDavServerOptions, \"auth\"> = {\n      enabled: input.enabled ?? false,\n      host: input.host ?? \"127.0.0.1\",\n      port: input.port,\n      allowlistDirs: input.allowlistDirs,\n      auth: input.auth ? validateWebDavAuth(input.auth) : undefined,\n    };\n\n    if (!Array.isArray(options.allowlistDirs) || options.allowlistDirs.length === 0) {\n      throw new Error(\"webdav allowlistDirs must include at least one directory\");\n    }\n    if (!Number.isInteger(options.port) || options.port < 0 || options.port > 65535) {\n      throw new Error(`invalid webdav port: ${options.port}`);\n    }\n\n    const allowedRoots: AllowedRoot[] = [];\n    const aliasSet = new Set<string>();\n    for (const dir of options.allowlistDirs) {\n      const resolved = path.resolve(dir);\n      await mkdir(resolved, { recursive: true });\n      const canonical = await realpath(resolved);\n      const alias = path.basename(canonical) || \"root\";\n      if (aliasSet.has(alias)) {\n        throw new Error(`duplicate webdav allowlist alias: ${alias}`);\n      }\n      aliasSet.add(alias);\n      allowedRoots.push({ absolute: canonical, name: alias });\n    }\n\n    return new WebDavServer(options, allowedRoots);\n  }\n\n  async start(): Promise<WebDavServerStatus> {\n    if (!this.options.enabled) {\n      throw new Error(\"webdav server is disabled; set enabled=true to start\");\n    }\n    if (this.server && this.listening) {\n      return this.status();\n    }\n    if (this.startPromise) return this.startPromise;\n\n    const server = createServer((req, res) => {\n      this.handle(req, res).catch((err) => {\n        if (res.headersSent) {\n          res.destroy(err as Error);\n          return;\n        }\n        res.writeHead(500, { \"Content-Type\": \"text/plain; charset=utf-8\" });\n        res.end(\"webdav error\");\n      });\n    });\n    this.server = server;\n    this.listening = false;\n\n    this.startPromise = (async () => {\n      try {\n        await new Promise<void>((resolve, reject) => {\n          const onError = (err: Error) => {\n            server.removeListener(\"listening\", onListening);\n            server.removeListener(\"close\", onClose);\n            reject(err);\n          };\n          const onListening = () => {\n            server.removeListener(\"error\", onError);\n            server.removeListener(\"close\", onClose);\n            resolve();\n          };\n          const onClose = () => {\n            server.removeListener(\"error\", onError);\n            server.removeListener(\"listening\", onListening);\n            reject(new Error(\"webdav server closed before listening\"));\n          };\n          server.once(\"error\", onError);\n          server.once(\"listening\", onListening);\n          server.once(\"close\", onClose);\n          server.listen(this.options.port, this.options.host);\n        });\n      } catch (err) {\n        if (this.server === server) {\n          this.server = null;\n        }\n        this.listening = false;\n        server.close();\n        throw err;\n      }\n\n      const address = server.address();\n      if (address && typeof address !== \"string\") {\n        this.boundPort = address.port;\n      }\n      this.listening = true;\n\n      return this.status();\n    })();\n\n    try {\n      return await this.startPromise;\n    } finally {\n      this.startPromise = null;\n    }\n  }\n\n  async stop(): Promise<void> {\n    if (!this.server) return;\n    const server = this.server;\n    const pendingStart = this.startPromise;\n    await new Promise<void>((resolve, reject) => {\n      server.close((err) => {\n        if (err && (err as NodeJS.ErrnoException).code !== \"ERR_SERVER_NOT_RUNNING\") {\n          reject(err);\n          return;\n        }\n        resolve();\n      });\n    });\n    await pendingStart?.catch(() => undefined);\n    if (this.server === server) {\n      this.server = null;\n    }\n    this.listening = false;\n    this.boundPort = this.options.port;\n  }\n\n  status(): WebDavServerStatus {\n    return {\n      running: this.server !== null && this.listening,\n      host: this.options.host,\n      port: this.boundPort,\n      rootCount: this.allowedRoots.length,\n    };\n  }\n\n  private async handle(req: IncomingMessage, res: ServerResponse): Promise<void> {\n    if (!this.isAuthorized(req)) {\n      res.writeHead(401, {\n        \"WWW-Authenticate\": 'Basic realm=\"Engram WebDAV\"',\n        \"Content-Type\": \"text/plain; charset=utf-8\",\n      });\n      res.end(\"authentication required\");\n      return;\n    }\n\n    const method = (req.method ?? \"GET\").toUpperCase();\n    if (method === \"OPTIONS\") {\n      res.writeHead(204, {\n        Allow: \"OPTIONS, PROPFIND, GET, HEAD\",\n        DAV: \"1\",\n      });\n      res.end();\n      return;\n    }\n\n    const parsed = new URL(req.url ?? \"/\", `http://${hostToUrlAuthority(this.options.host)}`);\n    const resolved = await this.resolvePath(parsed.pathname);\n    if (!resolved.ok) {\n      res.writeHead(resolved.code, { \"Content-Type\": \"text/plain; charset=utf-8\" });\n      res.end(resolved.message);\n      return;\n    }\n\n    if (method === \"PROPFIND\") {\n      await this.handlePropfind(resolved.absolutePath, resolved.rootAbsolute, resolved.displayPath, res);\n      return;\n    }\n\n    if (method === \"GET\" || method === \"HEAD\") {\n      await this.handleRead(method, resolved.absolutePath, resolved.rootAbsolute, res);\n      return;\n    }\n\n    res.writeHead(405, {\n      Allow: \"OPTIONS, PROPFIND, GET, HEAD\",\n      \"Content-Type\": \"text/plain; charset=utf-8\",\n    });\n    res.end(\"method not allowed\");\n  }\n\n  private isAuthorized(req: IncomingMessage): boolean {\n    if (!this.options.auth) return true;\n    const raw = req.headers.authorization;\n    if (!raw) return false;\n    const separator = raw.indexOf(\" \");\n    if (separator <= 0) return false;\n    const scheme = raw.slice(0, separator).toLowerCase();\n    if (scheme !== \"basic\") return false;\n    const encodedPart = raw.slice(separator + 1).trim();\n    if (!encodedPart) return false;\n\n    try {\n      const decoded = Buffer.from(encodedPart, \"base64\").toString(\"utf-8\");\n      const credentialSeparator = decoded.indexOf(\":\");\n      if (credentialSeparator < 0) return false;\n      const username = decoded.slice(0, credentialSeparator);\n      const password = decoded.slice(credentialSeparator + 1);\n      const usernameOk = this.timingSafeStringEqual(username, this.options.auth.username);\n      const passwordOk = this.timingSafeStringEqual(password, this.options.auth.password);\n      return Boolean((usernameOk ? 1 : 0) & (passwordOk ? 1 : 0));\n    } catch {\n      return false;\n    }\n  }\n\n  private timingSafeStringEqual(a: string, b: string): boolean {\n    const left = this.encodeAuthField(a);\n    const right = this.encodeAuthField(b);\n    if (!left || !right) return false;\n    return timingSafeEqual(left, right);\n  }\n\n  private encodeAuthField(value: string): Buffer | null {\n    const maxBytes = 512;\n    const encoded = Buffer.from(value, \"utf-8\");\n    if (encoded.length > maxBytes) return null;\n    const out = Buffer.alloc(2 + maxBytes);\n    out.writeUInt16BE(encoded.length, 0);\n    encoded.copy(out, 2);\n    return out;\n  }\n\n  private async resolvePath(requestPathname: string): Promise<\n    | { ok: true; absolutePath: string; displayPath: string; rootAbsolute: string }\n    | { ok: false; code: number; message: string }\n  > {\n    let decodedPath: string;\n    try {\n      decodedPath = decodeURIComponent(requestPathname || \"/\");\n    } catch {\n      return { ok: false, code: 400, message: \"invalid path encoding\" };\n    }\n    if (decodedPath.includes(\"\\0\")) {\n      return { ok: false, code: 400, message: \"invalid path\" };\n    }\n\n    const normalized = path.posix.normalize(decodedPath);\n    const segments = normalized.split(\"/\").filter((segment) => segment.length > 0);\n\n    if (segments.length === 0) {\n      return { ok: false, code: 403, message: \"root listing is not allowed\" };\n    }\n\n    const rootName = segments[0];\n    const root = this.allowedRoots.find((entry) => entry.name === rootName);\n    if (!root) {\n      return { ok: false, code: 403, message: \"path is outside allowlist\" };\n    }\n\n    const relative = segments.slice(1);\n    if (relative.some((segment) => segment === \"..\" || segment.includes(\"\\\\\"))) {\n      return { ok: false, code: 403, message: \"path traversal is not allowed\" };\n    }\n\n    const candidate = path.resolve(root.absolute, ...relative);\n    if (!this.isPathInside(root.absolute, candidate)) {\n      return { ok: false, code: 403, message: \"path escaped allowlist\" };\n    }\n\n    try {\n      const canonicalCandidate = await realpath(candidate);\n      if (!this.isPathInside(root.absolute, canonicalCandidate)) {\n        return { ok: false, code: 403, message: \"path escaped allowlist via symlink\" };\n      }\n      return { ok: true, absolutePath: canonicalCandidate, displayPath: `/${segments.join(\"/\")}`, rootAbsolute: root.absolute };\n    } catch (err) {\n      const code = (err as NodeJS.ErrnoException).code;\n      if (code === \"ENOENT\") {\n        return { ok: true, absolutePath: candidate, displayPath: `/${segments.join(\"/\")}`, rootAbsolute: root.absolute };\n      }\n      if (code === \"ENOTDIR\" || code === \"ELOOP\") {\n        return { ok: false, code: 400, message: \"invalid path\" };\n      }\n      throw err;\n    }\n  }\n\n  private async handleRead(\n    method: \"GET\" | \"HEAD\",\n    absolutePath: string,\n    rootAbsolute: string,\n    res: ServerResponse,\n  ): Promise<void> {\n    const revalidated = await this.revalidatePathInsideRoot(absolutePath, rootAbsolute);\n    if (!revalidated.ok) {\n      res.writeHead(revalidated.code, { \"Content-Type\": \"text/plain; charset=utf-8\" });\n      res.end(revalidated.message);\n      return;\n    }\n    const opened = await openWebDavFileForRead(revalidated.absolutePath);\n    if (!opened.ok) {\n      res.writeHead(opened.code, { \"Content-Type\": \"text/plain; charset=utf-8\" });\n      res.end(opened.message);\n      return;\n    }\n\n    const { handle, size } = opened;\n\n    try {\n      res.writeHead(200, {\n        \"Content-Length\": String(size),\n        \"Content-Type\": \"application/octet-stream\",\n      });\n\n      if (method === \"HEAD\") {\n        res.end();\n        return;\n      }\n\n      await pipeline(handle.createReadStream({ autoClose: false }), res);\n    } finally {\n      await handle.close().catch(() => {});\n    }\n  }\n\n  private async handlePropfind(\n    absolutePath: string,\n    rootAbsolute: string,\n    displayPath: string,\n    res: ServerResponse,\n  ): Promise<void> {\n    const revalidated = await this.revalidatePathInsideRoot(absolutePath, rootAbsolute);\n    if (!revalidated.ok) {\n      res.writeHead(revalidated.code, { \"Content-Type\": \"text/plain; charset=utf-8\" });\n      res.end(revalidated.message);\n      return;\n    }\n    absolutePath = revalidated.absolutePath;\n    let info;\n    try {\n      info = await stat(absolutePath);\n    } catch {\n      res.writeHead(404, { \"Content-Type\": \"text/plain; charset=utf-8\" });\n      res.end(\"not found\");\n      return;\n    }\n\n    const entries: string[] = [];\n    if (info.isDirectory()) {\n      const children = await readdir(absolutePath, { withFileTypes: true });\n      for (const child of children) {\n        const childHref = toEncodedHref(`${displayPath.replace(/\\/$/, \"\")}/${child.name}`);\n        entries.push(`\n  <d:response>\n    <d:href>${xmlEscape(childHref)}</d:href>\n    <d:propstat><d:prop><d:resourcetype>${child.isDirectory() ? \"<d:collection/>\" : \"\"}</d:resourcetype></d:prop><d:status>HTTP/1.1 200 OK</d:status></d:propstat>\n  </d:response>`);\n      }\n    }\n\n    const xml = `<?xml version=\"1.0\" encoding=\"utf-8\"?>\n<d:multistatus xmlns:d=\"DAV:\">\n  <d:response>\n    <d:href>${xmlEscape(toEncodedHref(displayPath))}</d:href>\n    <d:propstat><d:prop><d:resourcetype>${info.isDirectory() ? \"<d:collection/>\" : \"\"}</d:resourcetype></d:prop><d:status>HTTP/1.1 200 OK</d:status></d:propstat>\n  </d:response>${entries.join(\"\")}\n</d:multistatus>`;\n\n    res.writeHead(207, { \"Content-Type\": \"application/xml; charset=utf-8\" });\n    res.end(xml);\n  }\n\n  private isPathInside(root: string, target: string): boolean {\n    if (target === root) return true;\n    if (root === path.parse(root).root) {\n      return target.startsWith(root);\n    }\n    return target.startsWith(`${root}${path.sep}`);\n  }\n\n  private async revalidatePathInsideRoot(\n    absolutePath: string,\n    rootAbsolute: string,\n  ): Promise<\n    | { ok: true; absolutePath: string }\n    | { ok: false; code: number; message: string }\n  > {\n    try {\n      const canonical = await realpath(absolutePath);\n      if (!this.isPathInside(rootAbsolute, canonical)) {\n        return { ok: false, code: 403, message: \"path escaped allowlist via symlink\" };\n      }\n      return { ok: true, absolutePath: canonical };\n    } catch (err) {\n      const code = (err as NodeJS.ErrnoException).code;\n      if (code === \"ENOENT\" || code === \"ENOTDIR\") {\n        return { ok: false, code: 404, message: \"not found\" };\n      }\n      if (code === \"ELOOP\") {\n        return { ok: false, code: 403, message: \"path escaped allowlist via symlink\" };\n      }\n      throw err;\n    }\n  }\n}\n\nfunction xmlEscape(value: string): string {\n  return value\n    .replaceAll(\"&\", \"&amp;\")\n    .replaceAll(\"<\", \"&lt;\")\n    .replaceAll(\">\", \"&gt;\")\n    .replaceAll('\"', \"&quot;\")\n    .replaceAll(\"'\", \"&apos;\");\n}\n\nfunction toEncodedHref(pathname: string): string {\n  return pathname\n    .split(\"/\")\n    .map((segment) => encodeURIComponent(segment))\n    .join(\"/\");\n}\n"],"mappings":";AAAA,SAAS,iBAAiB;AAE1B,SAAS,OAAO,MAAM,SAAS,UAAU,YAAY;AACrD,SAAS,oBAA4E;AACrF,SAAS,uBAAuB;AAChC,OAAO,UAAU;AACjB,SAAS,gBAAgB;AACzB,SAAS,WAAW;AAEb,SAAS,mBAAmB,MAAsB;AACvD,MAAI,KAAK,SAAS,GAAG,KAAK,CAAC,KAAK,WAAW,GAAG,KAAK,CAAC,KAAK,SAAS,GAAG,GAAG;AACtE,WAAO,IAAI,IAAI;AAAA,EACjB;AACA,SAAO;AACT;AA+BA,SAAS,mBAAmB,MAA8B;AACxD,MAAI,OAAO,KAAK,aAAa,YAAY,KAAK,SAAS,KAAK,EAAE,WAAW,GAAG;AAC1E,UAAM,IAAI,MAAM,iDAAiD;AAAA,EACnE;AACA,MAAI,OAAO,KAAK,aAAa,YAAY,KAAK,SAAS,KAAK,EAAE,WAAW,GAAG;AAC1E,UAAM,IAAI,MAAM,iDAAiD;AAAA,EACnE;AACA,SAAO;AACT;AAEA,eAAsB,sBAAsB,cAAqD;AAC/F,MAAI,SAA4B;AAChC,MAAI;AACF,aAAS,MAAM,KAAK,cAAc,UAAU,WAAW,UAAU,UAAU;AAC3E,UAAM,OAAO,MAAM,OAAO,KAAK;AAC/B,QAAI,CAAC,KAAK,OAAO,GAAG;AAClB,YAAM,OAAO,MAAM,EAAE,MAAM,MAAM;AAAA,MAAC,CAAC;AACnC,aAAO,EAAE,IAAI,OAAO,MAAM,KAAK,SAAS,qBAAqB;AAAA,IAC/D;AACA,WAAO,EAAE,IAAI,MAAM,QAAQ,MAAM,KAAK,KAAK;AAAA,EAC7C,SAAS,KAAK;AACZ,UAAM,QAAQ,MAAM,EAAE,MAAM,MAAM;AAAA,IAAC,CAAC;AACpC,UAAM,OAAQ,IAA8B;AAC5C,QAAI,SAAS,SAAS;AACpB,aAAO,EAAE,IAAI,OAAO,MAAM,KAAK,SAAS,qCAAqC;AAAA,IAC/E;AACA,QAAI,SAAS,YAAY,SAAS,WAAW;AAC3C,aAAO,EAAE,IAAI,OAAO,MAAM,KAAK,SAAS,YAAY;AAAA,IACtD;AACA,WAAO,EAAE,IAAI,OAAO,MAAM,KAAK,SAAS,YAAY;AAAA,EACtD;AACF;AAEO,IAAM,eAAN,MAAM,cAAa;AAAA,EACP;AAAA,EACA;AAAA,EACT,SAAwB;AAAA,EACxB,eAAmD;AAAA,EACnD,YAAY;AAAA,EACZ;AAAA,EAEA,YACN,SACA,cACA;AACA,SAAK,UAAU;AACf,SAAK,eAAe;AACpB,SAAK,YAAY,QAAQ;AAAA,EAC3B;AAAA,EAEA,aAAa,OAAO,OAAmD;AACrE,UAAM,UAA2F;AAAA,MAC/F,SAAS,MAAM,WAAW;AAAA,MAC1B,MAAM,MAAM,QAAQ;AAAA,MACpB,MAAM,MAAM;AAAA,MACZ,eAAe,MAAM;AAAA,MACrB,MAAM,MAAM,OAAO,mBAAmB,MAAM,IAAI,IAAI;AAAA,IACtD;AAEA,QAAI,CAAC,MAAM,QAAQ,QAAQ,aAAa,KAAK,QAAQ,cAAc,WAAW,GAAG;AAC/E,YAAM,IAAI,MAAM,0DAA0D;AAAA,IAC5E;AACA,QAAI,CAAC,OAAO,UAAU,QAAQ,IAAI,KAAK,QAAQ,OAAO,KAAK,QAAQ,OAAO,OAAO;AAC/E,YAAM,IAAI,MAAM,wBAAwB,QAAQ,IAAI,EAAE;AAAA,IACxD;AAEA,UAAM,eAA8B,CAAC;AACrC,UAAM,WAAW,oBAAI,IAAY;AACjC,eAAW,OAAO,QAAQ,eAAe;AACvC,YAAM,WAAW,KAAK,QAAQ,GAAG;AACjC,YAAM,MAAM,UAAU,EAAE,WAAW,KAAK,CAAC;AACzC,YAAM,YAAY,MAAM,SAAS,QAAQ;AACzC,YAAM,QAAQ,KAAK,SAAS,SAAS,KAAK;AAC1C,UAAI,SAAS,IAAI,KAAK,GAAG;AACvB,cAAM,IAAI,MAAM,qCAAqC,KAAK,EAAE;AAAA,MAC9D;AACA,eAAS,IAAI,KAAK;AAClB,mBAAa,KAAK,EAAE,UAAU,WAAW,MAAM,MAAM,CAAC;AAAA,IACxD;AAEA,WAAO,IAAI,cAAa,SAAS,YAAY;AAAA,EAC/C;AAAA,EAEA,MAAM,QAAqC;AACzC,QAAI,CAAC,KAAK,QAAQ,SAAS;AACzB,YAAM,IAAI,MAAM,sDAAsD;AAAA,IACxE;AACA,QAAI,KAAK,UAAU,KAAK,WAAW;AACjC,aAAO,KAAK,OAAO;AAAA,IACrB;AACA,QAAI,KAAK,aAAc,QAAO,KAAK;AAEnC,UAAM,SAAS,aAAa,CAAC,KAAK,QAAQ;AACxC,WAAK,OAAO,KAAK,GAAG,EAAE,MAAM,CAAC,QAAQ;AACnC,YAAI,IAAI,aAAa;AACnB,cAAI,QAAQ,GAAY;AACxB;AAAA,QACF;AACA,YAAI,UAAU,KAAK,EAAE,gBAAgB,4BAA4B,CAAC;AAClE,YAAI,IAAI,cAAc;AAAA,MACxB,CAAC;AAAA,IACH,CAAC;AACD,SAAK,SAAS;AACd,SAAK,YAAY;AAEjB,SAAK,gBAAgB,YAAY;AAC/B,UAAI;AACF,cAAM,IAAI,QAAc,CAAC,SAAS,WAAW;AAC3C,gBAAM,UAAU,CAAC,QAAe;AAC9B,mBAAO,eAAe,aAAa,WAAW;AAC9C,mBAAO,eAAe,SAAS,OAAO;AACtC,mBAAO,GAAG;AAAA,UACZ;AACA,gBAAM,cAAc,MAAM;AACxB,mBAAO,eAAe,SAAS,OAAO;AACtC,mBAAO,eAAe,SAAS,OAAO;AACtC,oBAAQ;AAAA,UACV;AACA,gBAAM,UAAU,MAAM;AACpB,mBAAO,eAAe,SAAS,OAAO;AACtC,mBAAO,eAAe,aAAa,WAAW;AAC9C,mBAAO,IAAI,MAAM,uCAAuC,CAAC;AAAA,UAC3D;AACA,iBAAO,KAAK,SAAS,OAAO;AAC5B,iBAAO,KAAK,aAAa,WAAW;AACpC,iBAAO,KAAK,SAAS,OAAO;AAC5B,iBAAO,OAAO,KAAK,QAAQ,MAAM,KAAK,QAAQ,IAAI;AAAA,QACpD,CAAC;AAAA,MACH,SAAS,KAAK;AACZ,YAAI,KAAK,WAAW,QAAQ;AAC1B,eAAK,SAAS;AAAA,QAChB;AACA,aAAK,YAAY;AACjB,eAAO,MAAM;AACb,cAAM;AAAA,MACR;AAEA,YAAM,UAAU,OAAO,QAAQ;AAC/B,UAAI,WAAW,OAAO,YAAY,UAAU;AAC1C,aAAK,YAAY,QAAQ;AAAA,MAC3B;AACA,WAAK,YAAY;AAEjB,aAAO,KAAK,OAAO;AAAA,IACrB,GAAG;AAEH,QAAI;AACF,aAAO,MAAM,KAAK;AAAA,IACpB,UAAE;AACA,WAAK,eAAe;AAAA,IACtB;AAAA,EACF;AAAA,EAEA,MAAM,OAAsB;AAC1B,QAAI,CAAC,KAAK,OAAQ;AAClB,UAAM,SAAS,KAAK;AACpB,UAAM,eAAe,KAAK;AAC1B,UAAM,IAAI,QAAc,CAAC,SAAS,WAAW;AAC3C,aAAO,MAAM,CAAC,QAAQ;AACpB,YAAI,OAAQ,IAA8B,SAAS,0BAA0B;AAC3E,iBAAO,GAAG;AACV;AAAA,QACF;AACA,gBAAQ;AAAA,MACV,CAAC;AAAA,IACH,CAAC;AACD,UAAM,cAAc,MAAM,MAAM,MAAS;AACzC,QAAI,KAAK,WAAW,QAAQ;AAC1B,WAAK,SAAS;AAAA,IAChB;AACA,SAAK,YAAY;AACjB,SAAK,YAAY,KAAK,QAAQ;AAAA,EAChC;AAAA,EAEA,SAA6B;AAC3B,WAAO;AAAA,MACL,SAAS,KAAK,WAAW,QAAQ,KAAK;AAAA,MACtC,MAAM,KAAK,QAAQ;AAAA,MACnB,MAAM,KAAK;AAAA,MACX,WAAW,KAAK,aAAa;AAAA,IAC/B;AAAA,EACF;AAAA,EAEA,MAAc,OAAO,KAAsB,KAAoC;AAC7E,QAAI,CAAC,KAAK,aAAa,GAAG,GAAG;AAC3B,UAAI,UAAU,KAAK;AAAA,QACjB,oBAAoB;AAAA,QACpB,gBAAgB;AAAA,MAClB,CAAC;AACD,UAAI,IAAI,yBAAyB;AACjC;AAAA,IACF;AAEA,UAAM,UAAU,IAAI,UAAU,OAAO,YAAY;AACjD,QAAI,WAAW,WAAW;AACxB,UAAI,UAAU,KAAK;AAAA,QACjB,OAAO;AAAA,QACP,KAAK;AAAA,MACP,CAAC;AACD,UAAI,IAAI;AACR;AAAA,IACF;AAEA,UAAM,SAAS,IAAI,IAAI,IAAI,OAAO,KAAK,UAAU,mBAAmB,KAAK,QAAQ,IAAI,CAAC,EAAE;AACxF,UAAM,WAAW,MAAM,KAAK,YAAY,OAAO,QAAQ;AACvD,QAAI,CAAC,SAAS,IAAI;AAChB,UAAI,UAAU,SAAS,MAAM,EAAE,gBAAgB,4BAA4B,CAAC;AAC5E,UAAI,IAAI,SAAS,OAAO;AACxB;AAAA,IACF;AAEA,QAAI,WAAW,YAAY;AACzB,YAAM,KAAK,eAAe,SAAS,cAAc,SAAS,cAAc,SAAS,aAAa,GAAG;AACjG;AAAA,IACF;AAEA,QAAI,WAAW,SAAS,WAAW,QAAQ;AACzC,YAAM,KAAK,WAAW,QAAQ,SAAS,cAAc,SAAS,cAAc,GAAG;AAC/E;AAAA,IACF;AAEA,QAAI,UAAU,KAAK;AAAA,MACjB,OAAO;AAAA,MACP,gBAAgB;AAAA,IAClB,CAAC;AACD,QAAI,IAAI,oBAAoB;AAAA,EAC9B;AAAA,EAEQ,aAAa,KAA+B;AAClD,QAAI,CAAC,KAAK,QAAQ,KAAM,QAAO;AAC/B,UAAM,MAAM,IAAI,QAAQ;AACxB,QAAI,CAAC,IAAK,QAAO;AACjB,UAAM,YAAY,IAAI,QAAQ,GAAG;AACjC,QAAI,aAAa,EAAG,QAAO;AAC3B,UAAM,SAAS,IAAI,MAAM,GAAG,SAAS,EAAE,YAAY;AACnD,QAAI,WAAW,QAAS,QAAO;AAC/B,UAAM,cAAc,IAAI,MAAM,YAAY,CAAC,EAAE,KAAK;AAClD,QAAI,CAAC,YAAa,QAAO;AAEzB,QAAI;AACF,YAAM,UAAU,OAAO,KAAK,aAAa,QAAQ,EAAE,SAAS,OAAO;AACnE,YAAM,sBAAsB,QAAQ,QAAQ,GAAG;AAC/C,UAAI,sBAAsB,EAAG,QAAO;AACpC,YAAM,WAAW,QAAQ,MAAM,GAAG,mBAAmB;AACrD,YAAM,WAAW,QAAQ,MAAM,sBAAsB,CAAC;AACtD,YAAM,aAAa,KAAK,sBAAsB,UAAU,KAAK,QAAQ,KAAK,QAAQ;AAClF,YAAM,aAAa,KAAK,sBAAsB,UAAU,KAAK,QAAQ,KAAK,QAAQ;AAClF,aAAO,SAAS,aAAa,IAAI,MAAM,aAAa,IAAI,EAAE;AAAA,IAC5D,QAAQ;AACN,aAAO;AAAA,IACT;AAAA,EACF;AAAA,EAEQ,sBAAsB,GAAW,GAAoB;AAC3D,UAAM,OAAO,KAAK,gBAAgB,CAAC;AACnC,UAAM,QAAQ,KAAK,gBAAgB,CAAC;AACpC,QAAI,CAAC,QAAQ,CAAC,MAAO,QAAO;AAC5B,WAAO,gBAAgB,MAAM,KAAK;AAAA,EACpC;AAAA,EAEQ,gBAAgB,OAA8B;AACpD,UAAM,WAAW;AACjB,UAAM,UAAU,OAAO,KAAK,OAAO,OAAO;AAC1C,QAAI,QAAQ,SAAS,SAAU,QAAO;AACtC,UAAM,MAAM,OAAO,MAAM,IAAI,QAAQ;AACrC,QAAI,cAAc,QAAQ,QAAQ,CAAC;AACnC,YAAQ,KAAK,KAAK,CAAC;AACnB,WAAO;AAAA,EACT;AAAA,EAEA,MAAc,YAAY,iBAGxB;AACA,QAAI;AACJ,QAAI;AACF,oBAAc,mBAAmB,mBAAmB,GAAG;AAAA,IACzD,QAAQ;AACN,aAAO,EAAE,IAAI,OAAO,MAAM,KAAK,SAAS,wBAAwB;AAAA,IAClE;AACA,QAAI,YAAY,SAAS,IAAI,GAAG;AAC9B,aAAO,EAAE,IAAI,OAAO,MAAM,KAAK,SAAS,eAAe;AAAA,IACzD;AAEA,UAAM,aAAa,KAAK,MAAM,UAAU,WAAW;AACnD,UAAM,WAAW,WAAW,MAAM,GAAG,EAAE,OAAO,CAAC,YAAY,QAAQ,SAAS,CAAC;AAE7E,QAAI,SAAS,WAAW,GAAG;AACzB,aAAO,EAAE,IAAI,OAAO,MAAM,KAAK,SAAS,8BAA8B;AAAA,IACxE;AAEA,UAAM,WAAW,SAAS,CAAC;AAC3B,UAAM,OAAO,KAAK,aAAa,KAAK,CAAC,UAAU,MAAM,SAAS,QAAQ;AACtE,QAAI,CAAC,MAAM;AACT,aAAO,EAAE,IAAI,OAAO,MAAM,KAAK,SAAS,4BAA4B;AAAA,IACtE;AAEA,UAAM,WAAW,SAAS,MAAM,CAAC;AACjC,QAAI,SAAS,KAAK,CAAC,YAAY,YAAY,QAAQ,QAAQ,SAAS,IAAI,CAAC,GAAG;AAC1E,aAAO,EAAE,IAAI,OAAO,MAAM,KAAK,SAAS,gCAAgC;AAAA,IAC1E;AAEA,UAAM,YAAY,KAAK,QAAQ,KAAK,UAAU,GAAG,QAAQ;AACzD,QAAI,CAAC,KAAK,aAAa,KAAK,UAAU,SAAS,GAAG;AAChD,aAAO,EAAE,IAAI,OAAO,MAAM,KAAK,SAAS,yBAAyB;AAAA,IACnE;AAEA,QAAI;AACF,YAAM,qBAAqB,MAAM,SAAS,SAAS;AACnD,UAAI,CAAC,KAAK,aAAa,KAAK,UAAU,kBAAkB,GAAG;AACzD,eAAO,EAAE,IAAI,OAAO,MAAM,KAAK,SAAS,qCAAqC;AAAA,MAC/E;AACA,aAAO,EAAE,IAAI,MAAM,cAAc,oBAAoB,aAAa,IAAI,SAAS,KAAK,GAAG,CAAC,IAAI,cAAc,KAAK,SAAS;AAAA,IAC1H,SAAS,KAAK;AACZ,YAAM,OAAQ,IAA8B;AAC5C,UAAI,SAAS,UAAU;AACrB,eAAO,EAAE,IAAI,MAAM,cAAc,WAAW,aAAa,IAAI,SAAS,KAAK,GAAG,CAAC,IAAI,cAAc,KAAK,SAAS;AAAA,MACjH;AACA,UAAI,SAAS,aAAa,SAAS,SAAS;AAC1C,eAAO,EAAE,IAAI,OAAO,MAAM,KAAK,SAAS,eAAe;AAAA,MACzD;AACA,YAAM;AAAA,IACR;AAAA,EACF;AAAA,EAEA,MAAc,WACZ,QACA,cACA,cACA,KACe;AACf,UAAM,cAAc,MAAM,KAAK,yBAAyB,cAAc,YAAY;AAClF,QAAI,CAAC,YAAY,IAAI;AACnB,UAAI,UAAU,YAAY,MAAM,EAAE,gBAAgB,4BAA4B,CAAC;AAC/E,UAAI,IAAI,YAAY,OAAO;AAC3B;AAAA,IACF;AACA,UAAM,SAAS,MAAM,sBAAsB,YAAY,YAAY;AACnE,QAAI,CAAC,OAAO,IAAI;AACd,UAAI,UAAU,OAAO,MAAM,EAAE,gBAAgB,4BAA4B,CAAC;AAC1E,UAAI,IAAI,OAAO,OAAO;AACtB;AAAA,IACF;AAEA,UAAM,EAAE,QAAQ,KAAK,IAAI;AAEzB,QAAI;AACF,UAAI,UAAU,KAAK;AAAA,QACjB,kBAAkB,OAAO,IAAI;AAAA,QAC7B,gBAAgB;AAAA,MAClB,CAAC;AAED,UAAI,WAAW,QAAQ;AACrB,YAAI,IAAI;AACR;AAAA,MACF;AAEA,YAAM,SAAS,OAAO,iBAAiB,EAAE,WAAW,MAAM,CAAC,GAAG,GAAG;AAAA,IACnE,UAAE;AACA,YAAM,OAAO,MAAM,EAAE,MAAM,MAAM;AAAA,MAAC,CAAC;AAAA,IACrC;AAAA,EACF;AAAA,EAEA,MAAc,eACZ,cACA,cACA,aACA,KACe;AACf,UAAM,cAAc,MAAM,KAAK,yBAAyB,cAAc,YAAY;AAClF,QAAI,CAAC,YAAY,IAAI;AACnB,UAAI,UAAU,YAAY,MAAM,EAAE,gBAAgB,4BAA4B,CAAC;AAC/E,UAAI,IAAI,YAAY,OAAO;AAC3B;AAAA,IACF;AACA,mBAAe,YAAY;AAC3B,QAAI;AACJ,QAAI;AACF,aAAO,MAAM,KAAK,YAAY;AAAA,IAChC,QAAQ;AACN,UAAI,UAAU,KAAK,EAAE,gBAAgB,4BAA4B,CAAC;AAClE,UAAI,IAAI,WAAW;AACnB;AAAA,IACF;AAEA,UAAM,UAAoB,CAAC;AAC3B,QAAI,KAAK,YAAY,GAAG;AACtB,YAAM,WAAW,MAAM,QAAQ,cAAc,EAAE,eAAe,KAAK,CAAC;AACpE,iBAAW,SAAS,UAAU;AAC5B,cAAM,YAAY,cAAc,GAAG,YAAY,QAAQ,OAAO,EAAE,CAAC,IAAI,MAAM,IAAI,EAAE;AACjF,gBAAQ,KAAK;AAAA;AAAA,cAEP,UAAU,SAAS,CAAC;AAAA,0CACQ,MAAM,YAAY,IAAI,oBAAoB,EAAE;AAAA,gBACtE;AAAA,MACV;AAAA,IACF;AAEA,UAAM,MAAM;AAAA;AAAA;AAAA,cAGF,UAAU,cAAc,WAAW,CAAC,CAAC;AAAA,0CACT,KAAK,YAAY,IAAI,oBAAoB,EAAE;AAAA,iBACpE,QAAQ,KAAK,EAAE,CAAC;AAAA;AAG7B,QAAI,UAAU,KAAK,EAAE,gBAAgB,iCAAiC,CAAC;AACvE,QAAI,IAAI,GAAG;AAAA,EACb;AAAA,EAEQ,aAAa,MAAc,QAAyB;AAC1D,QAAI,WAAW,KAAM,QAAO;AAC5B,QAAI,SAAS,KAAK,MAAM,IAAI,EAAE,MAAM;AAClC,aAAO,OAAO,WAAW,IAAI;AAAA,IAC/B;AACA,WAAO,OAAO,WAAW,GAAG,IAAI,GAAG,KAAK,GAAG,EAAE;AAAA,EAC/C;AAAA,EAEA,MAAc,yBACZ,cACA,cAIA;AACA,QAAI;AACF,YAAM,YAAY,MAAM,SAAS,YAAY;AAC7C,UAAI,CAAC,KAAK,aAAa,cAAc,SAAS,GAAG;AAC/C,eAAO,EAAE,IAAI,OAAO,MAAM,KAAK,SAAS,qCAAqC;AAAA,MAC/E;AACA,aAAO,EAAE,IAAI,MAAM,cAAc,UAAU;AAAA,IAC7C,SAAS,KAAK;AACZ,YAAM,OAAQ,IAA8B;AAC5C,UAAI,SAAS,YAAY,SAAS,WAAW;AAC3C,eAAO,EAAE,IAAI,OAAO,MAAM,KAAK,SAAS,YAAY;AAAA,MACtD;AACA,UAAI,SAAS,SAAS;AACpB,eAAO,EAAE,IAAI,OAAO,MAAM,KAAK,SAAS,qCAAqC;AAAA,MAC/E;AACA,YAAM;AAAA,IACR;AAAA,EACF;AACF;AAEA,SAAS,UAAU,OAAuB;AACxC,SAAO,MACJ,WAAW,KAAK,OAAO,EACvB,WAAW,KAAK,MAAM,EACtB,WAAW,KAAK,MAAM,EACtB,WAAW,KAAK,QAAQ,EACxB,WAAW,KAAK,QAAQ;AAC7B;AAEA,SAAS,cAAc,UAA0B;AAC/C,SAAO,SACJ,MAAM,GAAG,EACT,IAAI,CAAC,YAAY,mBAAmB,OAAO,CAAC,EAC5C,KAAK,GAAG;AACb;","names":[]}

package/dist/{chunk-MRILGULB.js → chunk-V2RCP53Q.js}

@@ -1,6 +1,6 @@
 import {
   StorageManager
-} from "./chunk-VBJ7V5SK.js";
+} from "./chunk-UIPDNLXA.js";
 
 // src/semantic-rule-promotion.ts
 function normalizeRuleWhitespace(value) {
@@ -132,4 +132,4 @@ async function promoteSemanticRuleFromMemory(options) {
 export {
   promoteSemanticRuleFromMemory
 };
-//# sourceMappingURL=chunk-MRILGULB.js.map
+//# sourceMappingURL=chunk-V2RCP53Q.js.map

package/dist/{chunk-XKECPATV.js → chunk-VFUEZZBS.js}

@@ -1,7 +1,7 @@
 // src/access-idempotency.ts
 import { mkdir, open, readFile, rename, stat, unlink, utimes, writeFile } from "fs/promises";
 import path from "path";
-import { createHash } from "crypto";
+import { createHash, randomUUID } from "crypto";
 var testHooks = null;
 function stableStringify(value) {
   return JSON.stringify(value, (_key, candidate) => {
@@ -136,8 +136,17 @@ var AccessIdempotencyStore = class {
     const lockHeartbeatMs = testHooks?.lockHeartbeatMs ?? Math.max(1e3, Math.floor(staleLockMs / 3));
     const startedAt = Date.now();
     while (true) {
+      const ownerToken = `${process.pid}:${randomUUID()}`;
       try {
         const handle = await open(lockPath, "wx");
+        try {
+          await testHooks?.beforeLockOwnerWrite?.(lockPath, ownerToken);
+          await handle.writeFile(ownerToken, "utf-8");
+        } catch (error) {
+          await handle.close().catch(() => void 0);
+          await unlink(lockPath).catch(() => void 0);
+          throw error;
+        }
         let heartbeat = null;
         if (lockHeartbeatMs > 0) {
           heartbeat = setInterval(() => {
@@ -152,14 +161,24 @@ var AccessIdempotencyStore = class {
             clearInterval(heartbeat);
           }
           await handle.close().catch(() => void 0);
-          await unlink(lockPath).catch(() => void 0);
+          await unlinkLockIfOwner(lockPath, ownerToken, staleLockMs);
         }
       } catch (error) {
         if (!isAlreadyExistsError(error)) throw error;
         try {
           const lockStat = await stat(lockPath);
+          const lockOwner = await readLockOwner(lockPath);
           if (Date.now() - lockStat.mtimeMs > staleLockMs) {
-            await unlink(lockPath).catch(() => void 0);
+            await testHooks?.beforeStaleLockUnlink?.();
+            const removed = await unlinkStaleLockIfUnchanged({
+              lockPath,
+              observedOwner: lockOwner,
+              observedMtimeMs: lockStat.mtimeMs,
+              staleLockMs
+            });
+            if (!removed) {
+              await sleep(10);
+            }
             continue;
           }
         } catch {
@@ -190,6 +209,96 @@ var AccessIdempotencyStore = class {
 function isAlreadyExistsError(error) {
   return typeof error === "object" && error !== null && "code" in error && error.code === "EEXIST";
 }
+async function readLockOwner(lockPath) {
+  try {
+    return await readFile(lockPath, "utf-8");
+  } catch {
+    return null;
+  }
+}
+async function unlinkLockIfOwner(lockPath, ownerToken, staleLockMs) {
+  const reclaimHandle = await openStaleReclaimLock(`${lockPath}.reclaim`, staleLockMs);
+  if (!reclaimHandle) return;
+  try {
+    await reclaimHandle.writeFile(`${process.pid}:${Date.now()}`, "utf-8");
+    await unlinkLockIfOwnerWhileReclaimHeld(lockPath, ownerToken);
+  } finally {
+    await reclaimHandle.close().catch(() => void 0);
+    await unlink(`${lockPath}.reclaim`).catch(() => void 0);
+  }
+}
+async function unlinkLockIfOwnerWhileReclaimHeld(lockPath, ownerToken) {
+  let handle;
+  try {
+    handle = await open(lockPath, "r");
+  } catch {
+    return;
+  }
+  try {
+    const openedStat = await handle.stat();
+    const currentOwner = await handle.readFile("utf-8");
+    if (currentOwner !== ownerToken) return;
+    let currentStat;
+    try {
+      currentStat = await stat(lockPath);
+    } catch {
+      return;
+    }
+    if (!isSameFileIdentity(openedStat, currentStat)) return;
+  } finally {
+    await handle.close().catch(() => void 0);
+  }
+  await unlink(lockPath).catch(() => void 0);
+}
+function isSameFileIdentity(left, right) {
+  return left.dev === right.dev && left.ino === right.ino;
+}
+async function unlinkStaleLockIfUnchanged(options) {
+  const reclaimPath = `${options.lockPath}.reclaim`;
+  const reclaimHandle = await openStaleReclaimLock(reclaimPath, options.staleLockMs);
+  if (!reclaimHandle) return false;
+  try {
+    await reclaimHandle.writeFile(`${process.pid}:${Date.now()}`, "utf-8");
+    return await unlinkStaleLockIfStillOwned(options);
+  } finally {
+    await reclaimHandle.close().catch(() => void 0);
+    await unlink(reclaimPath).catch(() => void 0);
+  }
+}
+async function openStaleReclaimLock(reclaimPath, staleLockMs) {
+  try {
+    return await open(reclaimPath, "wx");
+  } catch (error) {
+    if (!isAlreadyExistsError(error)) throw error;
+  }
+  try {
+    const reclaimStat = await stat(reclaimPath);
+    if (Date.now() - reclaimStat.mtimeMs <= staleLockMs) return null;
+    await unlink(reclaimPath);
+  } catch {
+    return null;
+  }
+  try {
+    return await open(reclaimPath, "wx");
+  } catch (error) {
+    if (isAlreadyExistsError(error)) return null;
+    throw error;
+  }
+}
+async function unlinkStaleLockIfStillOwned(options) {
+  let currentStat;
+  try {
+    currentStat = await stat(options.lockPath);
+  } catch {
+    return true;
+  }
+  if (currentStat.mtimeMs !== options.observedMtimeMs) return false;
+  if (Date.now() - currentStat.mtimeMs <= options.staleLockMs) return false;
+  const currentOwner = await readLockOwner(options.lockPath);
+  if (currentOwner !== options.observedOwner) return false;
+  await unlink(options.lockPath);
+  return true;
+}
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -199,4 +308,4 @@ export {
   setAccessIdempotencyTestHooks,
   AccessIdempotencyStore
 };
-//# sourceMappingURL=chunk-XKECPATV.js.map
+//# sourceMappingURL=chunk-VFUEZZBS.js.map

package/dist/chunk-VFUEZZBS.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/access-idempotency.ts"],"sourcesContent":["import { mkdir, open, readFile, rename, stat, unlink, utimes, writeFile } from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { createHash, randomUUID } from \"node:crypto\";\n\ntype AccessIdempotencyEntry = {\n  recordedAt: string;\n  requestHash: string;\n  response: unknown;\n};\n\ntype AccessIdempotencyTestHooks = {\n  beforeFlushWrite?: () => Promise<void> | void;\n  lockTimeoutMs?: number;\n  staleLockMs?: number;\n  lockHeartbeatMs?: number;\n  beforeLockOwnerWrite?: (lockPath: string, ownerToken: string) => Promise<void> | void;\n  beforeStaleLockUnlink?: () => Promise<void> | void;\n};\n\nlet testHooks: AccessIdempotencyTestHooks | null = null;\n\nfunction stableStringify(value: unknown): string {\n  return JSON.stringify(value, (_key, candidate) => {\n    if (!candidate || typeof candidate !== \"object\" || Array.isArray(candidate)) {\n      return candidate;\n    }\n    return Object.keys(candidate)\n      .sort()\n      .reduce<Record<string, unknown>>((acc, key) => {\n        acc[key] = (candidate as Record<string, unknown>)[key];\n        return acc;\n      }, {});\n  });\n}\n\nexport function hashAccessIdempotencyPayload(payload: unknown): string {\n  return createHash(\"sha256\").update(stableStringify(payload)).digest(\"hex\");\n}\n\nexport function setAccessIdempotencyTestHooks(hooks: AccessIdempotencyTestHooks | null): void {\n  testHooks = hooks;\n}\n\nexport class AccessIdempotencyStore {\n  private readonly statePath: string;\n  private readonly lockPath: string;\n  private readonly keyLockDir: string;\n  private loadedMtimeMs = 0;\n  private state: Record<string, AccessIdempotencyEntry> = {};\n  private writeQueue: Promise<void> = Promise.resolve();\n\n  constructor(memoryDir: string) {\n    this.statePath = path.join(memoryDir, \"state\", \"access-idempotency.json\");\n    this.lockPath = `${this.statePath}.lock`;\n    this.keyLockDir = path.join(memoryDir, \"state\", \"access-idempotency-locks\");\n  }\n\n  async get(key: string, requestHash: string): Promise<{ response?: unknown; conflict: boolean }> {\n    await this.writeQueue.catch(() => {});\n    await this.reload({ forceRefresh: true });\n    const entry = this.state[key];\n    if (!entry) return { conflict: false };\n    if (entry.requestHash !== requestHash) {\n      return { conflict: true };\n    }\n    return {\n      conflict: false,\n      response: JSON.parse(JSON.stringify(entry.response)),\n    };\n  }\n\n  async put(key: string, requestHash: string, response: unknown): Promise<void> {\n    await this.withWriteQueue(async () => {\n      await this.reload({ forceRefresh: true });\n      this.state[key] = {\n        recordedAt: new Date().toISOString(),\n        requestHash,\n        response: JSON.parse(JSON.stringify(response)),\n      };\n      await this.prune();\n      await this.flush();\n    });\n  }\n\n  async withKeyLock<T>(key: string, callback: () => Promise<T>): Promise<T> {\n    const keyHash = createHash(\"sha256\").update(key).digest(\"hex\");\n    const keyLockPath = path.join(this.keyLockDir, `${keyHash}.lock`);\n    return this.withExclusiveFileLock(keyLockPath, callback);\n  }\n\n  private async reload(options: { forceRefresh?: boolean } = {}): Promise<void> {\n    if (options.forceRefresh === true) {\n      try {\n        const fileStat = await stat(this.statePath);\n        if (fileStat.mtimeMs < this.loadedMtimeMs) {\n          return;\n        }\n      } catch {\n        this.state = {};\n        this.loadedMtimeMs = 0;\n        return;\n      }\n    }\n    try {\n      const raw = await readFile(this.statePath, \"utf-8\");\n      const parsed = JSON.parse(raw) as Record<string, AccessIdempotencyEntry>;\n      if (parsed && typeof parsed === \"object\") {\n        this.state = parsed;\n        this.loadedMtimeMs = await this.readMtimeMs();\n        return;\n      }\n    } catch {\n      // Missing or malformed state should fail open to an empty store.\n    }\n    this.state = {};\n    this.loadedMtimeMs = 0;\n  }\n\n  private async prune(): Promise<void> {\n    const entries = Object.entries(this.state);\n    if (entries.length <= 512) return;\n    entries\n      .sort((left, right) => right[1].recordedAt.localeCompare(left[1].recordedAt))\n      .slice(512)\n      .forEach(([key]) => {\n        delete this.state[key];\n      });\n  }\n\n  private async flush(): Promise<void> {\n    await mkdir(path.dirname(this.statePath), { recursive: true });\n    await this.withExclusiveFileLock(this.lockPath, async () => {\n      try {\n        const raw = await readFile(this.statePath, \"utf-8\");\n        const parsed = JSON.parse(raw) as Record<string, AccessIdempotencyEntry>;\n        if (parsed && typeof parsed === \"object\") {\n          this.state = {\n            ...parsed,\n            ...this.state,\n          };\n          await this.prune();\n        }\n      } catch {\n        // Fail open when there is no pre-existing shared state to merge.\n      }\n\n      await testHooks?.beforeFlushWrite?.();\n\n      const tempPath = `${this.statePath}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`;\n      try {\n        await writeFile(tempPath, JSON.stringify(this.state, null, 2), \"utf-8\");\n        await rename(tempPath, this.statePath);\n      } finally {\n        await unlink(tempPath).catch(() => undefined);\n      }\n      this.loadedMtimeMs = await this.readMtimeMs();\n    });\n  }\n\n  private async readMtimeMs(): Promise<number> {\n    try {\n      return (await stat(this.statePath)).mtimeMs;\n    } catch {\n      return 0;\n    }\n  }\n\n  private async withExclusiveFileLock<T>(lockPath: string, callback: () => Promise<T>): Promise<T> {\n    await mkdir(path.dirname(lockPath), { recursive: true });\n    const timeoutMs = testHooks?.lockTimeoutMs ?? 5_000;\n    const staleLockMs = testHooks?.staleLockMs ?? 30_000;\n    const lockHeartbeatMs = testHooks?.lockHeartbeatMs ?? Math.max(1_000, Math.floor(staleLockMs / 3));\n    const startedAt = Date.now();\n\n    while (true) {\n      const ownerToken = `${process.pid}:${randomUUID()}`;\n      try {\n        const handle = await open(lockPath, \"wx\");\n        try {\n          await testHooks?.beforeLockOwnerWrite?.(lockPath, ownerToken);\n          await handle.writeFile(ownerToken, \"utf-8\");\n        } catch (error) {\n          await handle.close().catch(() => undefined);\n          await unlink(lockPath).catch(() => undefined);\n          throw error;\n        }\n        let heartbeat: NodeJS.Timeout | null = null;\n        if (lockHeartbeatMs > 0) {\n          heartbeat = setInterval(() => {\n            void utimes(lockPath, new Date(), new Date()).catch(() => undefined);\n          }, lockHeartbeatMs);\n          heartbeat.unref?.();\n        }\n        try {\n          return await callback();\n        } finally {\n          if (heartbeat) {\n            clearInterval(heartbeat);\n          }\n          await handle.close().catch(() => undefined);\n          await unlinkLockIfOwner(lockPath, ownerToken, staleLockMs);\n        }\n      } catch (error) {\n        if (!isAlreadyExistsError(error)) throw error;\n        try {\n          const lockStat = await stat(lockPath);\n          const lockOwner = await readLockOwner(lockPath);\n          if (Date.now() - lockStat.mtimeMs > staleLockMs) {\n            await testHooks?.beforeStaleLockUnlink?.();\n            const removed = await unlinkStaleLockIfUnchanged({\n              lockPath,\n              observedOwner: lockOwner,\n              observedMtimeMs: lockStat.mtimeMs,\n              staleLockMs,\n            });\n            if (!removed) {\n              await sleep(10);\n            }\n            continue;\n          }\n        } catch {\n          continue;\n        }\n        if (Date.now() - startedAt > timeoutMs) {\n          throw new Error(\"timed out acquiring access idempotency lock\");\n        }\n        await sleep(10);\n      }\n    }\n  }\n\n  private async withWriteQueue<T>(callback: () => Promise<T>): Promise<T> {\n    const previous = this.writeQueue;\n    let release!: () => void;\n    this.writeQueue = new Promise<void>((resolve) => {\n      release = resolve;\n    });\n    await previous.catch(() => {});\n    try {\n      return await callback();\n    } finally {\n      release();\n    }\n  }\n}\n\nfunction isAlreadyExistsError(error: unknown): boolean {\n  return typeof error === \"object\" && error !== null && \"code\" in error && error.code === \"EEXIST\";\n}\n\nasync function readLockOwner(lockPath: string): Promise<string | null> {\n  try {\n    return await readFile(lockPath, \"utf-8\");\n  } catch {\n    return null;\n  }\n}\n\nasync function unlinkLockIfOwner(lockPath: string, ownerToken: string, staleLockMs: number): Promise<void> {\n  const reclaimHandle = await openStaleReclaimLock(`${lockPath}.reclaim`, staleLockMs);\n  if (!reclaimHandle) return;\n  try {\n    await reclaimHandle.writeFile(`${process.pid}:${Date.now()}`, \"utf-8\");\n    await unlinkLockIfOwnerWhileReclaimHeld(lockPath, ownerToken);\n  } finally {\n    await reclaimHandle.close().catch(() => undefined);\n    await unlink(`${lockPath}.reclaim`).catch(() => undefined);\n  }\n}\n\nasync function unlinkLockIfOwnerWhileReclaimHeld(lockPath: string, ownerToken: string): Promise<void> {\n  let handle: Awaited<ReturnType<typeof open>>;\n  try {\n    handle = await open(lockPath, \"r\");\n  } catch {\n    return;\n  }\n  try {\n    const openedStat = await handle.stat();\n    const currentOwner = await handle.readFile(\"utf-8\");\n    if (currentOwner !== ownerToken) return;\n    let currentStat: Awaited<ReturnType<typeof stat>>;\n    try {\n      currentStat = await stat(lockPath);\n    } catch {\n      return;\n    }\n    if (!isSameFileIdentity(openedStat, currentStat)) return;\n  } finally {\n    await handle.close().catch(() => undefined);\n  }\n  await unlink(lockPath).catch(() => undefined);\n}\n\nfunction isSameFileIdentity(left: Awaited<ReturnType<typeof stat>>, right: Awaited<ReturnType<typeof stat>>): boolean {\n  return left.dev === right.dev && left.ino === right.ino;\n}\n\nasync function unlinkStaleLockIfUnchanged(options: {\n  lockPath: string;\n  observedOwner: string | null;\n  observedMtimeMs: number;\n  staleLockMs: number;\n}): Promise<boolean> {\n  const reclaimPath = `${options.lockPath}.reclaim`;\n  const reclaimHandle = await openStaleReclaimLock(reclaimPath, options.staleLockMs);\n  if (!reclaimHandle) return false;\n  try {\n    await reclaimHandle.writeFile(`${process.pid}:${Date.now()}`, \"utf-8\");\n    return await unlinkStaleLockIfStillOwned(options);\n  } finally {\n    await reclaimHandle.close().catch(() => undefined);\n    await unlink(reclaimPath).catch(() => undefined);\n  }\n}\n\nasync function openStaleReclaimLock(\n  reclaimPath: string,\n  staleLockMs: number,\n): Promise<Awaited<ReturnType<typeof open>> | null> {\n  try {\n    return await open(reclaimPath, \"wx\");\n  } catch (error) {\n    if (!isAlreadyExistsError(error)) throw error;\n  }\n\n  try {\n    const reclaimStat = await stat(reclaimPath);\n    if (Date.now() - reclaimStat.mtimeMs <= staleLockMs) return null;\n    await unlink(reclaimPath);\n  } catch {\n    return null;\n  }\n\n  try {\n    return await open(reclaimPath, \"wx\");\n  } catch (error) {\n    if (isAlreadyExistsError(error)) return null;\n    throw error;\n  }\n}\n\nasync function unlinkStaleLockIfStillOwned(options: {\n  lockPath: string;\n  observedOwner: string | null;\n  observedMtimeMs: number;\n  staleLockMs: number;\n}): Promise<boolean> {\n  let currentStat: Awaited<ReturnType<typeof stat>>;\n  try {\n    currentStat = await stat(options.lockPath);\n  } catch {\n    return true;\n  }\n  if (currentStat.mtimeMs !== options.observedMtimeMs) return false;\n  if (Date.now() - currentStat.mtimeMs <= options.staleLockMs) return false;\n  const currentOwner = await readLockOwner(options.lockPath);\n  if (currentOwner !== options.observedOwner) return false;\n  await unlink(options.lockPath);\n  return true;\n}\n\nfunction sleep(ms: number): Promise<void> {\n  return new Promise((resolve) => setTimeout(resolve, ms));\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-FSFEQI74.js → chunk-W7L6HXUC.js}

@@ -1,6 +1,6 @@
 import {
   readUtilityLearningSnapshot
-} from "./chunk-PYXS46O7.js";
+} from "./chunk-3BP57I6J.js";
 import {
   clamp01
 } from "./chunk-TBBDFYXW.js";
@@ -65,4 +65,4 @@ export {
   applyUtilityRankingRuntimeDelta,
   applyUtilityPromotionRuntimePolicy
 };
-//# sourceMappingURL=chunk-FSFEQI74.js.map
+//# sourceMappingURL=chunk-W7L6HXUC.js.map

package/dist/{chunk-3IQ2TR4N.js → chunk-WLEB7WCG.js}

@@ -2,7 +2,7 @@ import {
   discoverMemoryExtensions,
   renderExtensionsFooter,
   resolveExtensionsRoot
-} from "./chunk-EJI5XIBB.js";
+} from "./chunk-JLNBQWZ2.js";
 import {
   log
 } from "./chunk-2ODBA7MQ.js";
@@ -113,4 +113,4 @@ export {
   formatDaySummaryMemories,
   buildExtensionsFooterForSummary
 };
-//# sourceMappingURL=chunk-3IQ2TR4N.js.map
+//# sourceMappingURL=chunk-WLEB7WCG.js.map

package/dist/{chunk-GL6I6MEQ.js → chunk-WSGF57U2.js}

@@ -1,9 +1,9 @@
 import {
   parseMessageParts
-} from "./chunk-3APJ5EVB.js";
+} from "./chunk-XKIQZXUB.js";
 import {
   recordObjectiveStateSnapshot
-} from "./chunk-5UM2VJ6D.js";
+} from "./chunk-UEY3VB6W.js";
 
 // src/objective-state-writers.ts
 import crypto from "crypto";
@@ -644,4 +644,4 @@ export {
   recordObjectiveStateSnapshotsFromAgentMessages,
   recordObjectiveStateSnapshotsFromObservedMessages
 };
-//# sourceMappingURL=chunk-GL6I6MEQ.js.map
+//# sourceMappingURL=chunk-WSGF57U2.js.map

package/dist/{chunk-KNKUID7G.js → chunk-X7Y7WX73.js}

@@ -3,6 +3,10 @@ import {
   readHeader,
   secureStoreDir
 } from "./chunk-BJMBJZ2Y.js";
+import {
+  KDF_SALT_LENGTH,
+  deriveKey
+} from "./chunk-FP2373TW.js";
 import {
   open,
   seal
@@ -68,7 +72,14 @@ async function decryptCapsuleFile(opts) {
       `decryptCapsuleFile: unsupported encrypted-capsule format version ${version} (this build supports versions 1 and 2): ${opts.encPath}`
     );
   }
-  const { key, envelopeOffset } = resolveKeyAndOffset(buf, version, opts.memoryDir, "decryptCapsuleFile", opts.encPath);
+  const { key, envelopeOffset } = resolveKeyAndOffset(
+    buf,
+    version,
+    opts.memoryDir,
+    "decryptCapsuleFile",
+    opts.encPath,
+    opts.passphrase
+  );
   const envelope = buf.subarray(envelopeOffset);
   const basename = path.basename(opts.encPath);
   const aad = Buffer.from(basename, "utf-8");
@@ -84,7 +95,7 @@ async function decryptCapsuleFile(opts) {
   await writeFile(gzPath, plaintext);
   return { gzPath };
 }
-async function decryptCapsuleFileInMemory(encPath, memoryDir) {
+async function decryptCapsuleFileInMemory(encPath, memoryDir, options = {}) {
   const buf = await readFile(encPath);
   if (buf.length < MIN_ENC_SIZE_V1) {
     throw new Error(
@@ -102,7 +113,14 @@ async function decryptCapsuleFileInMemory(encPath, memoryDir) {
       `decryptCapsuleFileInMemory: unsupported encrypted-capsule format version ${version} (this build supports versions 1 and 2): ${encPath}`
     );
   }
-  const { key, envelopeOffset } = resolveKeyAndOffset(buf, version, memoryDir, "decryptCapsuleFileInMemory", encPath);
+  const { key, envelopeOffset } = resolveKeyAndOffset(
+    buf,
+    version,
+    memoryDir,
+    "decryptCapsuleFileInMemory",
+    encPath,
+    options.passphrase
+  );
   const envelope = buf.subarray(envelopeOffset);
   const basename = path.basename(encPath);
   const aad = Buffer.from(basename, "utf-8");
@@ -142,16 +160,21 @@ async function loadKdfSection(memoryDir) {
   return { json, salt };
 }
 function getKeyOrThrow(memoryDir, action) {
+  if (!memoryDir) {
+    throw new Error(
+      `Secure-store memoryDir is required \u2014 cannot ${action} without either an unlocked keyring or a format-v2 passphrase.`
+    );
+  }
   const storeId = secureStoreDir(memoryDir);
   const key = getKey(storeId);
   if (key === null) {
     throw new Error(
-      `Secure-store is locked or not initialized \u2014 cannot ${action}. Run \`remnic secure-store unlock\` first, or \`remnic secure-store init\` if the store has never been initialized.`
+      `Secure-store is locked or not initialized \u2014 cannot ${action}. Run \`remnic secure-store unlock\` first, provide the original passphrase for a format-v2 archive restore, or run \`remnic secure-store init\` if the store has never been initialized.`
     );
   }
   return key;
 }
-function resolveKeyAndOffset(buf, version, memoryDir, caller, encPath) {
+function resolveKeyAndOffset(buf, version, memoryDir, caller, encPath, passphrase) {
   if (version === 1) {
     const key2 = getKeyOrThrow(memoryDir, "decrypt capsule");
     return { key: key2, envelopeOffset: MAGIC.length + 1 };
@@ -169,10 +192,53 @@ function resolveKeyAndOffset(buf, version, memoryDir, caller, encPath) {
       `${caller}: file too short for format v2 KDF params section (expected ${kdfLen} bytes): ${encPath}`
     );
   }
+  if (kdfLen <= 0) {
+    throw new Error(`${caller}: format v2 KDF params section is empty: ${encPath}`);
+  }
+  const kdfJson = buf.subarray(kdfJsonOffset, kdfJsonOffset + kdfLen).toString("utf-8");
+  const kdf = parseEmbeddedKdfSection(kdfJson, caller, encPath);
   const envelopeOffset = kdfJsonOffset + kdfLen;
+  if (passphrase !== void 0) {
+    if (passphrase.length === 0) {
+      throw new Error(`${caller}: passphrase must not be empty for format v2 archive restore`);
+    }
+    const key2 = deriveKey(kdf.algorithm, passphrase, kdf.salt, kdf.params);
+    return { key: key2, envelopeOffset };
+  }
   const key = getKeyOrThrow(memoryDir, "decrypt capsule");
   return { key, envelopeOffset };
 }
+function parseEmbeddedKdfSection(json, caller, encPath) {
+  let parsed;
+  try {
+    parsed = JSON.parse(json);
+  } catch (cause) {
+    throw new Error(`${caller}: format v2 KDF params are not valid JSON: ${encPath}`, { cause });
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new Error(`${caller}: format v2 KDF params must be a JSON object: ${encPath}`);
+  }
+  const obj = parsed;
+  const algorithm = obj.algorithm;
+  if (algorithm !== "scrypt" && algorithm !== "argon2id") {
+    throw new Error(`${caller}: unsupported format v2 KDF algorithm ${String(algorithm)}: ${encPath}`);
+  }
+  if (typeof obj.params !== "object" || obj.params === null || Array.isArray(obj.params)) {
+    throw new Error(`${caller}: format v2 KDF params.params must be an object: ${encPath}`);
+  }
+  if (typeof obj.salt !== "string" || !/^[0-9a-fA-F]+$/.test(obj.salt) || obj.salt.length % 2 !== 0) {
+    throw new Error(`${caller}: format v2 KDF salt must be an even-length hex string: ${encPath}`);
+  }
+  const salt = Buffer.from(obj.salt, "hex");
+  if (salt.length !== KDF_SALT_LENGTH) {
+    throw new Error(`${caller}: format v2 KDF salt decoded to ${salt.length} bytes, expected ${KDF_SALT_LENGTH}: ${encPath}`);
+  }
+  return {
+    algorithm,
+    params: obj.params,
+    salt
+  };
+}
 
 export {
   isEncryptedCapsuleFile,
@@ -180,4 +246,4 @@ export {
   decryptCapsuleFile,
   decryptCapsuleFileInMemory
 };
-//# sourceMappingURL=chunk-KNKUID7G.js.map
+//# sourceMappingURL=chunk-X7Y7WX73.js.map

package/dist/chunk-X7Y7WX73.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/transfer/capsule-crypto.ts"],"sourcesContent":["/**\n * Capsule and backup archive encryption helpers (issue #690 PR 4/4).\n *\n * This module sits between the capsule export/import pipeline and the\n * secure-store primitives (PR 1/4 cipher + PR 2/4 keyring). It handles:\n *\n *   - Wrapping a raw `.capsule.json.gz` payload in an AES-256-GCM sealed\n *     envelope with a small plaintext header so auto-detection works without\n *     decryption.\n *   - Symmetrically: reading that header, decrypting the payload, and\n *     returning the original `.capsule.json.gz` bytes.\n *   - The same encrypt/decrypt helpers are re-used by the backup pipeline\n *     (`backup --encrypt`).\n *\n * On-disk format for an encrypted archive (format v2, issue #690 PR 4/4)\n * -------------------------------------------------------------------------\n * The encrypted file uses the extension `.capsule.json.gz.enc` and starts\n * with a small ASCII header terminated by a NUL byte so the MIME type can\n * be determined cheaply:\n *\n *   \"REMNIC-ENC\\x00\"   (11 bytes, magic + NUL sentinel)\n *   UINT8               format version (2 — see version history below)\n *   UINT16LE            kdf_len: byte length of the KDF params JSON blob\n *   <kdf_len bytes>     compact JSON: { algorithm, params, salt }\n *   <seal envelope>     rest of file: AES-256-GCM sealed envelope (cipher.ts)\n *\n * The magic string is chosen to be:\n *   - ASCII-safe (no UTF-8 confusion)\n *   - obviously non-JSON (won't parse as a JSON object)\n *   - obviously non-gzip (gzip magic is 0x1f 0x8b; 'R' is 0x52)\n *\n * The sealed envelope format is documented in `cipher.ts`:\n *   [VERSION:1][SALT:16][IV:12][AUTHTAG:16][CIPHERTEXT:...]\n *\n * The original gzip bytes are the ciphertext. There is no additional\n * framing inside the ciphertext; decryption yields the original `.gz`\n * bytes verbatim.\n *\n * AAD\n * ---\n * The file's basename (without the `.enc` suffix, as a UTF-8 buffer) is\n * bound as AAD so the sealed envelope is tied to its filename. Renaming an\n * encrypted capsule file causes auth-tag failure on open. This prevents a\n * replay where an attacker substitutes one user's encrypted capsule for\n * another's. Callers MUST supply the same basename on encrypt and decrypt.\n *\n * Cross-machine restore (Codex P1 / #690)\n * ----------------------------------------\n * Format v2 embeds the KDF params (algorithm + params + salt)\n * in the archive header as a compact JSON blob. Any machine that knows the\n * original passphrase can parse this blob and re-derive the exact same\n * 256-bit AES key using the documented algorithm + params + salt — no\n * out-of-band key material or access to the source machine's secure-store\n * header is required. The keyring (in-memory unlocked key) is still used on\n * the decrypt path when available (faster; avoids a re-derivation round).\n */\n\nimport { open as openFileHandle, readFile, writeFile } from \"node:fs/promises\";\nimport path from \"node:path\";\n\nimport { open, seal } from \"../secure-store/cipher.js\";\nimport * as keyring from \"../secure-store/keyring.js\";\nimport { readHeader, secureStoreDir } from \"../secure-store/header.js\";\nimport {\n  deriveKey,\n  KDF_SALT_LENGTH,\n  type Argon2idParams,\n  type KdfAlgorithm,\n  type ScryptParams,\n} from \"../secure-store/kdf.js\";\n\n// ---------------------------------------------------------------------------\n// On-disk magic\n// ---------------------------------------------------------------------------\n\n/** ASCII magic + NUL sentinel — 11 bytes total. */\nconst MAGIC = Buffer.from(\"REMNIC-ENC\\x00\", \"ascii\");\n\n/**\n * Current format version byte.\n *\n * Version history:\n *   1 — original format: MAGIC(11) + VERSION(1) + ENVELOPE(...)\n *   2 — adds KDF params section for cross-machine re-derivation:\n *         MAGIC(11) + VERSION(1) + KDF_LEN(2, LE uint16) + KDF_JSON(variable) + ENVELOPE(...)\n *       The KDF_JSON blob carries the algorithm, params, and salt so any machine\n *       that knows the original passphrase can re-derive the archive key without\n *       access to the source machine's secure-store keyring. (Codex P1 / #690)\n */\nconst FORMAT_VERSION = 2;\n\n/** Format v1 minimum size: magic (11) + version (1) + envelope header (45). */\nconst MIN_ENC_SIZE_V1 = MAGIC.length + 1 + 45; // 45 = cipher.ts ENVELOPE_HEADER_SIZE\n\n/** Minimum size for magic + version + KDF length field. */\nconst MIN_ENC_SIZE = MAGIC.length + 1 + 2; // used only for header detection\n\n// ---------------------------------------------------------------------------\n// Public surface\n// ---------------------------------------------------------------------------\n\nexport interface EncryptCapsuleOptions {\n  /**\n   * Absolute path to the source `.capsule.json.gz` (or `.backup.tar.gz`)\n   * payload to encrypt.\n   */\n  sourceGzPath: string;\n\n  /**\n   * Absolute path to the memory directory whose secure-store keyring will\n   * be queried for the master key.\n   */\n  memoryDir: string;\n\n  /**\n   * Destination path for the encrypted output. If omitted, defaults to\n   * `sourceGzPath + \".enc\"`.\n   */\n  outPath?: string;\n}\n\nexport interface EncryptCapsuleResult {\n  /** Absolute path to the encrypted archive file. */\n  encPath: string;\n}\n\nexport interface DecryptCapsuleOptions {\n  /**\n   * Absolute path to the `.enc` encrypted archive to decrypt.\n   */\n  encPath: string;\n\n  /**\n   * Absolute path to the memory directory whose secure-store keyring will\n   * be queried for the master key when no passphrase is supplied. Required\n   * for v1 archives, optional for v2 passphrase-based restores.\n   */\n  memoryDir?: string;\n\n  /**\n   * Original secure-store passphrase. For format-v2 archives this is used\n   * with the embedded KDF params to restore on a machine that does not have\n   * the source memory directory's unlocked keyring entry.\n   */\n  passphrase?: string;\n\n  /**\n   * Destination path for the decrypted output. If omitted, defaults to\n   * `encPath` with the `.enc` suffix removed.\n   */\n  outPath?: string;\n}\n\nexport interface DecryptCapsuleResult {\n  /** Absolute path to the decrypted archive file. */\n  gzPath: string;\n}\n\n/**\n * Return `true` iff the given file path ends with `.enc` AND its first bytes\n * match the REMNIC-ENC magic header.\n *\n * Reads only the first `MAGIC.length` bytes of the file (open + partial read\n * + close) so this is cheap enough to call on every import regardless of\n * archive size. (Codex P2 / Cursor — previously read the entire file.)\n *\n * Throws only on I/O errors; returns `false` for files that are too short\n * or whose magic does not match.\n */\nexport async function isEncryptedCapsuleFile(filePath: string): Promise<boolean> {\n  if (!filePath.endsWith(\".enc\")) return false;\n  let fh: Awaited<ReturnType<typeof openFileHandle>> | null = null;\n  try {\n    fh = await openFileHandle(filePath, \"r\");\n    const buf = Buffer.allocUnsafe(MAGIC.length);\n    const { bytesRead } = await fh.read(buf, 0, MAGIC.length, 0);\n    if (bytesRead < MAGIC.length) return false;\n    return buf.equals(MAGIC);\n  } catch {\n    return false;\n  } finally {\n    if (fh !== null) {\n      await fh.close().catch(() => undefined);\n    }\n  }\n}\n\n/**\n * Encrypt a `.capsule.json.gz` (or `.backup.tar.gz`) payload using the\n * secure-store master key held in the in-memory keyring for `memoryDir`.\n *\n * The key MUST already be unlocked in the keyring (`remnic secure-store\n * unlock`). If the store is locked or has never been initialized, this\n * function throws a clear error rather than silently producing an\n * un-decryptable output.\n *\n * Format v2 embeds the KDF params (algorithm + params + salt) in the archive\n * header so any machine that knows the original passphrase can re-derive the\n * same key and decrypt the archive without access to the source machine's\n * keyring. (Codex P1 — cross-machine restore.)\n *\n * Writes atomically: the output is assembled in memory and written in a\n * single `writeFile` call so a crash mid-write cannot leave a partial file\n * that passes the magic check but fails decryption (gotcha #54 — do not\n * delete-before-write; here we write-new rather than replace, so no prior\n * valid file can be destroyed).\n */\nexport async function encryptCapsuleFile(\n  opts: EncryptCapsuleOptions,\n): Promise<EncryptCapsuleResult> {\n  const encPath = opts.outPath ?? `${opts.sourceGzPath}.enc`;\n  const key = getKeyOrThrow(opts.memoryDir, \"encrypt capsule\");\n\n  // Read the source payload.\n  const plaintext = await readFile(opts.sourceGzPath);\n\n  // Bind the output filename (without .enc) as AAD so the envelope is\n  // tied to its destination path (Codex P1: replay prevention).\n  const basename = path.basename(encPath);\n  const aad = Buffer.from(basename, \"utf-8\");\n\n  // Load the secure-store header to extract KDF params + canonical salt.\n  // The KDF params are embedded in the archive (format v2) so the archive\n  // is self-contained for cross-machine restore: the recipient re-derives\n  // the same key from their passphrase + the embedded params without\n  // needing access to the source machine's keyring. (Codex P1 / #690)\n  const kdfSection = await loadKdfSection(opts.memoryDir);\n\n  const envelope = seal(key, kdfSection.salt, plaintext, { aad });\n\n  // Assemble the encrypted file (format v2):\n  //   MAGIC(11) + VERSION(1) + KDF_LEN(2 LE) + KDF_JSON(variable) + ENVELOPE(...)\n  const versionBuf = Buffer.alloc(1);\n  versionBuf.writeUInt8(FORMAT_VERSION, 0);\n\n  const kdfJsonBuf = Buffer.from(kdfSection.json, \"utf-8\");\n  const kdfLenBuf = Buffer.alloc(2);\n  kdfLenBuf.writeUInt16LE(kdfJsonBuf.length, 0);\n\n  const output = Buffer.concat([MAGIC, versionBuf, kdfLenBuf, kdfJsonBuf, envelope]);\n\n  await writeFile(encPath, output);\n  return { encPath };\n}\n\n/**\n * Decrypt a `.enc` encrypted capsule or backup archive.\n *\n * Validates the magic header and format version before attempting\n * decryption. Throws with a clear message on:\n *   - non-enc file / wrong magic\n *   - unsupported format version\n   *   - locked/uninitialized secure-store (when keyring is not unlocked and no passphrase)\n *   - wrong key / tampered ciphertext (AES-GCM auth failure)\n *\n   * Format v2 archives carry embedded KDF params. If a `passphrase` is\n   * provided, the key is re-derived from the passphrase + embedded KDF params\n   * for cross-machine restore. Without a passphrase, an unlocked keyring key\n   * from `memoryDir` is used directly.\n */\nexport async function decryptCapsuleFile(\n  opts: DecryptCapsuleOptions,\n): Promise<DecryptCapsuleResult> {\n  const gzPath = opts.outPath ?? opts.encPath.replace(/\\.enc$/, \"\");\n\n  const buf = await readFile(opts.encPath);\n\n  // Magic check.\n  if (buf.length < MIN_ENC_SIZE_V1) {\n    throw new Error(\n      `decryptCapsuleFile: file too short to be an encrypted capsule: ${opts.encPath}`,\n    );\n  }\n  if (!buf.subarray(0, MAGIC.length).equals(MAGIC)) {\n    throw new Error(\n      `decryptCapsuleFile: file does not start with REMNIC-ENC magic: ${opts.encPath}`,\n    );\n  }\n\n  // Version check.\n  const version = buf.readUInt8(MAGIC.length);\n  if (version !== 1 && version !== 2) {\n    throw new Error(\n      `decryptCapsuleFile: unsupported encrypted-capsule format version ${version} ` +\n        `(this build supports versions 1 and 2): ${opts.encPath}`,\n    );\n  }\n\n  // Resolve the decryption key and the envelope offset.\n  const { key, envelopeOffset } = resolveKeyAndOffset(\n    buf,\n    version,\n    opts.memoryDir,\n    \"decryptCapsuleFile\",\n    opts.encPath,\n    opts.passphrase,\n  );\n\n  // The sealed envelope starts at `envelopeOffset`.\n  const envelope = buf.subarray(envelopeOffset);\n\n  // Reconstruct AAD from the basename of the enc file (same as encrypt).\n  const basename = path.basename(opts.encPath);\n  const aad = Buffer.from(basename, \"utf-8\");\n\n  let plaintext: Buffer;\n  try {\n    plaintext = open(key, envelope, { aad });\n  } catch (cause) {\n    throw new Error(\n      `decryptCapsuleFile: authentication failed — wrong passphrase, ` +\n        `tampered archive, or key mismatch. ` +\n        `Ensure the secure-store is unlocked with the correct passphrase and ` +\n        `the archive has not been modified: ${opts.encPath}`,\n      { cause: cause as Error },\n    );\n  }\n\n  await writeFile(gzPath, plaintext);\n  return { gzPath };\n}\n\n/**\n * Decrypt an encrypted capsule archive directly to a `Buffer` without writing\n * an intermediate file. Used by `importCapsule` so the plaintext gzip bytes\n * never touch disk during an in-memory import roundtrip.\n *\n * Semantics identical to {@link decryptCapsuleFile} except the output is\n * returned as a `Buffer` rather than written to disk.\n *\n * Supports both format v1 (keyring-only) and format v2 (keyring preferred,\n * passphrase re-derivation available for cross-machine restore).\n */\nexport async function decryptCapsuleFileInMemory(\n  encPath: string,\n  memoryDir?: string,\n  options: { passphrase?: string } = {},\n): Promise<Buffer> {\n  const buf = await readFile(encPath);\n\n  if (buf.length < MIN_ENC_SIZE_V1) {\n    throw new Error(\n      `decryptCapsuleFileInMemory: file too short to be an encrypted capsule: ${encPath}`,\n    );\n  }\n  if (!buf.subarray(0, MAGIC.length).equals(MAGIC)) {\n    throw new Error(\n      `decryptCapsuleFileInMemory: file does not start with REMNIC-ENC magic: ${encPath}`,\n    );\n  }\n\n  const version = buf.readUInt8(MAGIC.length);\n  if (version !== 1 && version !== 2) {\n    throw new Error(\n      `decryptCapsuleFileInMemory: unsupported encrypted-capsule format version ${version} ` +\n        `(this build supports versions 1 and 2): ${encPath}`,\n    );\n  }\n\n  const { key, envelopeOffset } = resolveKeyAndOffset(\n    buf,\n    version,\n    memoryDir,\n    \"decryptCapsuleFileInMemory\",\n    encPath,\n    options.passphrase,\n  );\n  const envelope = buf.subarray(envelopeOffset);\n\n  const basename = path.basename(encPath);\n  const aad = Buffer.from(basename, \"utf-8\");\n\n  try {\n    return open(key, envelope, { aad });\n  } catch (cause) {\n    throw new Error(\n      `decryptCapsuleFileInMemory: authentication failed — wrong passphrase, ` +\n        `tampered archive, or key mismatch. ` +\n        `Ensure the secure-store is unlocked with the correct passphrase and ` +\n        `the archive has not been modified: ${encPath}`,\n      { cause: cause as Error },\n    );\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Serializable KDF section embedded in format-v2 archives.\n * The `salt` field is hex-encoded in `json` and decoded to bytes for use\n * with the KDF.\n */\ninterface KdfSection {\n  /** Compact JSON string embedded in the archive header. */\n  json: string;\n  /** Decoded salt bytes (same value as the `salt` field in `json`). */\n  salt: Buffer;\n}\n\ninterface ParsedKdfSection {\n  algorithm: KdfAlgorithm;\n  params: ScryptParams | Argon2idParams;\n  salt: Buffer;\n}\n\n/**\n * Read the KDF params + canonical salt from the secure-store header and\n * return both a compact JSON representation (for embedding in the archive)\n * and the salt buffer (for passing to `seal`).\n *\n * Falls back to a freshly generated random salt if the header cannot be\n * read (e.g. in tests that skip header init). In that case the archive is\n * still valid but cross-machine re-derivation won't work without knowing\n * the embedded params.\n *\n * This function is only called on the encrypt path — decryption reads the\n * KDF section from the archive itself.\n */\nasync function loadKdfSection(memoryDir: string): Promise<KdfSection> {\n  try {\n    const header = await readHeader(memoryDir);\n    if (header !== null) {\n      const { decodeMetadataSalt } = await import(\"../secure-store/metadata.js\");\n      const salt = decodeMetadataSalt(header.metadata);\n      const kdf = header.metadata.kdf;\n      const json = JSON.stringify({\n        algorithm: kdf.algorithm,\n        params: kdf.params,\n        salt: salt.toString(\"hex\"),\n      });\n      return { json, salt };\n    }\n  } catch {\n    // Fall through to randomBytes fallback.\n  }\n  const { generateSalt } = await import(\"../secure-store/cipher.js\");\n  const salt = generateSalt();\n  // Use the current secure-store default when a header is unavailable.\n  const { DEFAULT_ARGON2ID_PARAMS } = await import(\"../secure-store/kdf.js\");\n  const json = JSON.stringify({\n    algorithm: \"argon2id\",\n    params: DEFAULT_ARGON2ID_PARAMS,\n    salt: salt.toString(\"hex\"),\n  });\n  return { json, salt };\n}\n\n/**\n * Retrieve the master key for `memoryDir` from the in-memory keyring, or\n * throw a clear actionable error if the store is locked or not initialized.\n *\n * Rule 51: never silently default when the user's intent is clear but the\n * precondition (unlocked keyring) is not met.\n */\nfunction getKeyOrThrow(memoryDir: string | undefined, action: string): Buffer {\n  if (!memoryDir) {\n    throw new Error(\n      `Secure-store memoryDir is required — cannot ${action} without either an unlocked keyring or a format-v2 passphrase.`,\n    );\n  }\n  const storeId = secureStoreDir(memoryDir);\n  const key = keyring.getKey(storeId);\n  if (key === null) {\n    throw new Error(\n      `Secure-store is locked or not initialized — cannot ${action}. ` +\n        `Run \\`remnic secure-store unlock\\` first, provide the original passphrase for ` +\n        `a format-v2 archive restore, or run \\`remnic secure-store init\\` if the store ` +\n        `has never been initialized.`,\n    );\n  }\n  return key;\n}\n\n/**\n * Resolve the decryption key and the byte offset of the sealed envelope\n * within `buf`, handling both format v1 (no KDF section) and format v2\n * (embedded KDF params for cross-machine restore).\n *\n * For v2 archives: a caller-supplied passphrase is derived against the\n * embedded KDF section for cross-machine restore. Without a passphrase, the\n * keyring is used as the fast local path.\n *\n * The KDF-params section serves two roles:\n *   1. Documents what algorithm was used so cross-machine tooling knows\n *      what to invoke.\n *   2. Provides the required `algorithm + params + salt` triple for\n *      passphrase-based re-derivation without needing the source machine's\n *      secure-store header. (Codex P1 / #690)\n */\nfunction resolveKeyAndOffset(\n  buf: Buffer,\n  version: number,\n  memoryDir: string | undefined,\n  caller: string,\n  encPath: string,\n  passphrase?: string,\n): { key: Buffer; envelopeOffset: number } {\n  if (version === 1) {\n    // v1: envelope starts immediately after magic (11) + version (1).\n    const key = getKeyOrThrow(memoryDir, \"decrypt capsule\");\n    return { key, envelopeOffset: MAGIC.length + 1 };\n  }\n\n  // v2: KDF_LEN(2 LE) + KDF_JSON(KDF_LEN bytes) + envelope.\n  const kdfLenOffset = MAGIC.length + 1; // after magic + version\n  if (buf.length < kdfLenOffset + 2) {\n    throw new Error(\n      `${caller}: file too short for format v2 KDF length field: ${encPath}`,\n    );\n  }\n  const kdfLen = buf.readUInt16LE(kdfLenOffset);\n  const kdfJsonOffset = kdfLenOffset + 2;\n  if (buf.length < kdfJsonOffset + kdfLen) {\n    throw new Error(\n      `${caller}: file too short for format v2 KDF params section (expected ${kdfLen} bytes): ${encPath}`,\n    );\n  }\n  if (kdfLen <= 0) {\n    throw new Error(`${caller}: format v2 KDF params section is empty: ${encPath}`);\n  }\n  const kdfJson = buf.subarray(kdfJsonOffset, kdfJsonOffset + kdfLen).toString(\"utf-8\");\n  const kdf = parseEmbeddedKdfSection(kdfJson, caller, encPath);\n  const envelopeOffset = kdfJsonOffset + kdfLen;\n\n  if (passphrase !== undefined) {\n    if (passphrase.length === 0) {\n      throw new Error(`${caller}: passphrase must not be empty for format v2 archive restore`);\n    }\n    const key = deriveKey(kdf.algorithm, passphrase, kdf.salt, kdf.params);\n    return { key, envelopeOffset };\n  }\n\n  const key = getKeyOrThrow(memoryDir, \"decrypt capsule\");\n  return { key, envelopeOffset };\n}\n\nfunction parseEmbeddedKdfSection(json: string, caller: string, encPath: string): ParsedKdfSection {\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(json);\n  } catch (cause) {\n    throw new Error(`${caller}: format v2 KDF params are not valid JSON: ${encPath}`, { cause: cause as Error });\n  }\n  if (typeof parsed !== \"object\" || parsed === null || Array.isArray(parsed)) {\n    throw new Error(`${caller}: format v2 KDF params must be a JSON object: ${encPath}`);\n  }\n  const obj = parsed as Record<string, unknown>;\n  const algorithm = obj.algorithm;\n  if (algorithm !== \"scrypt\" && algorithm !== \"argon2id\") {\n    throw new Error(`${caller}: unsupported format v2 KDF algorithm ${String(algorithm)}: ${encPath}`);\n  }\n  if (typeof obj.params !== \"object\" || obj.params === null || Array.isArray(obj.params)) {\n    throw new Error(`${caller}: format v2 KDF params.params must be an object: ${encPath}`);\n  }\n  if (typeof obj.salt !== \"string\" || !/^[0-9a-fA-F]+$/.test(obj.salt) || obj.salt.length % 2 !== 0) {\n    throw new Error(`${caller}: format v2 KDF salt must be an even-length hex string: ${encPath}`);\n  }\n  const salt = Buffer.from(obj.salt, \"hex\");\n  if (salt.length !== KDF_SALT_LENGTH) {\n    throw new Error(`${caller}: format v2 KDF salt decoded to ${salt.length} bytes, expected ${KDF_SALT_LENGTH}: ${encPath}`);\n  }\n  return {\n    algorithm,\n    params: obj.params as ScryptParams | Argon2idParams,\n    salt,\n  };\n}\n"],"mappings":"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","names":["salt","json","key"]}

package/dist/{chunk-5NPGSAVB.js → chunk-XEKAG3FM.js}

@@ -1,15 +1,23 @@
+import {
+  writeFileAtomically
+} from "./chunk-4426WSWL.js";
 import {
   log
 } from "./chunk-2ODBA7MQ.js";
 
 // src/relevance.ts
-import { mkdir, readFile, writeFile } from "fs/promises";
+import { mkdir, readFile } from "fs/promises";
 import path from "path";
 var RelevanceStore = class {
   statePath;
+  writeStateFile;
   state = {};
-  constructor(memoryDir) {
+  stateWriteChain = Promise.resolve();
+  constructor(memoryDir, options = {}) {
     this.statePath = path.join(memoryDir, "state", "relevance.json");
+    this.writeStateFile = options.writeStateFile ?? (async (filePath, content) => {
+      await writeFileAtomically(filePath, content);
+    });
   }
   async load() {
     try {
@@ -35,8 +43,7 @@ var RelevanceStore = class {
     };
     this.state[memoryId] = next;
     try {
-      await mkdir(path.dirname(this.statePath), { recursive: true });
-      await writeFile(this.statePath, JSON.stringify(this.state, null, 2), "utf-8");
+      await this.flushState();
     } catch (err) {
       log.debug(`relevance store write failed: ${err}`);
     }
@@ -52,9 +59,20 @@ var RelevanceStore = class {
     const down = Math.min(3, fb.down);
     return up * 0.05 - down * 0.1;
   }
+  flushState() {
+    const run = this.stateWriteChain.catch(() => void 0).then(async () => {
+      await mkdir(path.dirname(this.statePath), { recursive: true });
+      await this.writeStateFile(this.statePath, JSON.stringify(this.state, null, 2));
+    });
+    this.stateWriteChain = run.then(
+      () => void 0,
+      () => void 0
+    );
+    return run;
+  }
 };
 
 export {
   RelevanceStore
 };
-//# sourceMappingURL=chunk-5NPGSAVB.js.map
+//# sourceMappingURL=chunk-XEKAG3FM.js.map

package/dist/chunk-XEKAG3FM.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/relevance.ts"],"sourcesContent":["import { mkdir, readFile } from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { log } from \"./logger.js\";\nimport { writeFileAtomically } from \"./maintenance/atomic-file.js\";\nimport type { RelevanceFeedback } from \"./types.js\";\n\ntype RelevanceState = Record<string, RelevanceFeedback>;\ntype StateFileWriter = (filePath: string, content: string) => Promise<void>;\n\nexport class RelevanceStore {\n  private readonly statePath: string;\n  private readonly writeStateFile: StateFileWriter;\n  private state: RelevanceState = {};\n  private stateWriteChain: Promise<void> = Promise.resolve();\n\n  constructor(memoryDir: string, options: { writeStateFile?: StateFileWriter } = {}) {\n    this.statePath = path.join(memoryDir, \"state\", \"relevance.json\");\n    this.writeStateFile =\n      options.writeStateFile ??\n      (async (filePath, content) => {\n        await writeFileAtomically(filePath, content);\n      });\n  }\n\n  async load(): Promise<void> {\n    try {\n      const raw = await readFile(this.statePath, \"utf-8\");\n      const parsed = JSON.parse(raw) as RelevanceState;\n      if (parsed && typeof parsed === \"object\") this.state = parsed;\n    } catch {\n      this.state = {};\n    }\n  }\n\n  /**\n   * Record a thumbs up/down for a memory ID.\n   * This is intentionally lightweight; it should never block agent execution.\n   */\n  async record(memoryId: string, vote: \"up\" | \"down\", note?: string): Promise<void> {\n    const now = new Date().toISOString();\n    const existing = this.state[memoryId] ?? { up: 0, down: 0, lastUpdatedAt: now };\n    const next: RelevanceFeedback = {\n      up: existing.up + (vote === \"up\" ? 1 : 0),\n      down: existing.down + (vote === \"down\" ? 1 : 0),\n      lastUpdatedAt: now,\n      notes: note\n        ? [...(existing.notes ?? []).slice(-19), note]\n        : existing.notes,\n    };\n    this.state[memoryId] = next;\n\n    try {\n      await this.flushState();\n    } catch (err) {\n      log.debug(`relevance store write failed: ${err}`);\n    }\n  }\n\n  /**\n   * Convert feedback into a small score adjustment.\n   * Intended to be used as a tie-breaker/soft bias, not a hard filter.\n   */\n  adjustment(memoryId: string): number {\n    const fb = this.state[memoryId];\n    if (!fb) return 0;\n\n    // Cap effect to avoid runaway ranking distortion.\n    const up = Math.min(3, fb.up);\n    const down = Math.min(3, fb.down);\n\n    // Typical QMD scores are around 0-1; keep adjustments small.\n    return up * 0.05 - down * 0.10; // max +0.15, min -0.30\n  }\n\n  private flushState(): Promise<void> {\n    const run = this.stateWriteChain.catch(() => undefined).then(async () => {\n      await mkdir(path.dirname(this.statePath), { recursive: true });\n      await this.writeStateFile(this.statePath, JSON.stringify(this.state, null, 2));\n    });\n    this.stateWriteChain = run.then(\n      () => undefined,\n      () => undefined,\n    );\n    return run;\n  }\n}\n"],"mappings":";;;;;;;;AAAA,SAAS,OAAO,gBAAgB;AAChC,OAAO,UAAU;AAQV,IAAM,iBAAN,MAAqB;AAAA,EACT;AAAA,EACA;AAAA,EACT,QAAwB,CAAC;AAAA,EACzB,kBAAiC,QAAQ,QAAQ;AAAA,EAEzD,YAAY,WAAmB,UAAgD,CAAC,GAAG;AACjF,SAAK,YAAY,KAAK,KAAK,WAAW,SAAS,gBAAgB;AAC/D,SAAK,iBACH,QAAQ,mBACP,OAAO,UAAU,YAAY;AAC5B,YAAM,oBAAoB,UAAU,OAAO;AAAA,IAC7C;AAAA,EACJ;AAAA,EAEA,MAAM,OAAsB;AAC1B,QAAI;AACF,YAAM,MAAM,MAAM,SAAS,KAAK,WAAW,OAAO;AAClD,YAAM,SAAS,KAAK,MAAM,GAAG;AAC7B,UAAI,UAAU,OAAO,WAAW,SAAU,MAAK,QAAQ;AAAA,IACzD,QAAQ;AACN,WAAK,QAAQ,CAAC;AAAA,IAChB;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,MAAM,OAAO,UAAkB,MAAqB,MAA8B;AAChF,UAAM,OAAM,oBAAI,KAAK,GAAE,YAAY;AACnC,UAAM,WAAW,KAAK,MAAM,QAAQ,KAAK,EAAE,IAAI,GAAG,MAAM,GAAG,eAAe,IAAI;AAC9E,UAAM,OAA0B;AAAA,MAC9B,IAAI,SAAS,MAAM,SAAS,OAAO,IAAI;AAAA,MACvC,MAAM,SAAS,QAAQ,SAAS,SAAS,IAAI;AAAA,MAC7C,eAAe;AAAA,MACf,OAAO,OACH,CAAC,IAAI,SAAS,SAAS,CAAC,GAAG,MAAM,GAAG,GAAG,IAAI,IAC3C,SAAS;AAAA,IACf;AACA,SAAK,MAAM,QAAQ,IAAI;AAEvB,QAAI;AACF,YAAM,KAAK,WAAW;AAAA,IACxB,SAAS,KAAK;AACZ,UAAI,MAAM,iCAAiC,GAAG,EAAE;AAAA,IAClD;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,WAAW,UAA0B;AACnC,UAAM,KAAK,KAAK,MAAM,QAAQ;AAC9B,QAAI,CAAC,GAAI,QAAO;AAGhB,UAAM,KAAK,KAAK,IAAI,GAAG,GAAG,EAAE;AAC5B,UAAM,OAAO,KAAK,IAAI,GAAG,GAAG,IAAI;AAGhC,WAAO,KAAK,OAAO,OAAO;AAAA,EAC5B;AAAA,EAEQ,aAA4B;AAClC,UAAM,MAAM,KAAK,gBAAgB,MAAM,MAAM,MAAS,EAAE,KAAK,YAAY;AACvE,YAAM,MAAM,KAAK,QAAQ,KAAK,SAAS,GAAG,EAAE,WAAW,KAAK,CAAC;AAC7D,YAAM,KAAK,eAAe,KAAK,WAAW,KAAK,UAAU,KAAK,OAAO,MAAM,CAAC,CAAC;AAAA,IAC/E,CAAC;AACD,SAAK,kBAAkB,IAAI;AAAA,MACzB,MAAM;AAAA,MACN,MAAM;AAAA,IACR;AACA,WAAO;AAAA,EACT;AACF;","names":[]}