@alma-harness/core 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,71 @@
+# @alma-harness/core
+
+The contracts and the security core of [Alma](https://github.com/FabioFernandesCarneiro/alma)
+— a TypeScript runtime for multi-tenant agents operating on sensitive data.
+The engine that runs against them ships as
+[`@alma-harness/loop`](../loop).
+
+> **Status: pre-release.** Not yet published to npm. The API is still moving;
+> see the [roadmap](../../docs/architecture.md#12-adoption-roadmap).
+
+## What it owns
+
+The vocabulary every other package speaks, and the rules the engine may not
+bend. What a turn is allowed to do is defined here; the engine that enforces
+it lives in [`@alma-harness/loop`](../loop).
+
+- **Tenancy** (`Scope`, `scopePath`) — `{org, uid}` bound by closure. The model
+  never sees or chooses it; deriving it from a verified identity is the host
+  application's job.
+- **Lifecycle events** (`LifecycleHooks`, `Interceptor`) — the closed set of
+  typed seams an extension may attach to, capability-narrowing only.
+- **Tools** (`defineTool`) — capability by registration. What the model may
+  call is derived from the registry per step, never a list it can extend.
+  Outputs are bounded at registration (`maxOutputChars`, a default applies):
+  a result enters the transcript once and is re-sent forever, and removing
+  it later costs more than it saves.
+- **Routing** (`ModelPolicy`, `Sensitivity`, `Tier`) — complexity × sensitivity,
+  enforced at dispatch and never escalating through a delegate.
+- **Budget** (`BudgetCaps`, `priceUsage`, `SpendStore`) — dollar caps,
+  fail-closed pricing: an unpriced model never spends. `perTurnUsd` is a hard
+  stop (the malfunction guard); session and tenant-day caps are accounted
+  through the `SpendStore` seam with per-cap policy — `warn` by default (the
+  turn continues, the crossing is reported), `block` opt-in.
+- **Audit** (`AuditLog`) — access, routing, cost, recall and context trails. Where they
+  are written is swappable; *that* they are written is not.
+- **Turn coordination** (`TurnStore`) — the session lease and the idempotency
+  record (spec 030). A redelivered webhook replays the stored result instead of
+  re-executing tools and re-charging; two messages on one session serialize
+  instead of interleaving. Same idiom: where the record lives is swappable,
+  that a turn is claimed before it runs is not.
+- **Memory contracts** (`EpisodeStore`, `ProfileStore`, `MemoryErasure`, …) —
+  the interfaces live here because memory integrates with tenancy, audit and
+  routing; the implementations live in `@alma-harness/memory`.
+
+## What it must never do
+
+- Reach the filesystem, spawn a subprocess, or ship a shell. Ever.
+- Accept a scope from the model, or let a hook rewrite routing, budget or the
+  advertised tool set.
+- Depend on a provider SDK. The neutral message format is the boundary.
+
+## Testing helpers
+
+`@alma-harness/core/testing` ships reference implementations of the contracts
+this package publishes — a recording `AuditLog`, and the in-memory
+`SessionStore`, `SpendStore` and `TurnStore`. Nothing in it imports vitest. The shared
+storage contract suites every adapter must pass live in
+`@alma-harness/testing`; the in-memory memory stores in
+`@alma-harness/memory/testing`; the scripted `ModelClient` that drives the
+engine in [`@alma-harness/loop/testing`](../loop).
+
+```ts
+import { InMemorySessionStore, RecordingAuditLog } from "@alma-harness/core/testing";
+```
+
+## Documentation
+
+[Docs index](../../docs/README.md) · [Architecture](../../docs/architecture.md)
+· [Invariants](../../docs/invariants.md) · [Quickstart](../../examples/quickstart)
+
+Apache-2.0

package/dist/chunk-KPNXPUGR.js

@@ -0,0 +1,125 @@
+// src/scope.ts
+var InvalidScopeError = class extends Error {
+  constructor(segment, value) {
+    super(`Invalid scope ${segment}: ${JSON.stringify(value)}`);
+    this.name = "InvalidScopeError";
+  }
+};
+var SCOPE_SEGMENT = /^[A-Za-z0-9_-][A-Za-z0-9._-]*$/;
+function scopePath(scope) {
+  if (!SCOPE_SEGMENT.test(scope.org)) throw new InvalidScopeError("org", scope.org);
+  if (!SCOPE_SEGMENT.test(scope.uid)) throw new InvalidScopeError("uid", scope.uid);
+  return `tenants/${scope.org}/users/${scope.uid}`;
+}
+
+// src/text.ts
+function cutAtCodePoint(text, end) {
+  if (end <= 0) return "";
+  const last = text.charCodeAt(end - 1);
+  return text.slice(0, last >= 55296 && last <= 56319 ? end - 1 : end);
+}
+function hasMalformed(root) {
+  const stack = [root];
+  while (stack.length > 0) {
+    const value = stack.pop();
+    if (typeof value === "string") {
+      if (!value.isWellFormed()) return true;
+    } else if (Array.isArray(value)) {
+      for (const item of value) stack.push(item);
+    } else if (value !== null && typeof value === "object") {
+      for (const [key, item] of Object.entries(value)) {
+        if (!key.isWellFormed()) return true;
+        stack.push(item);
+      }
+    }
+  }
+  return false;
+}
+function repair(root) {
+  const leaf = (v) => typeof v === "string" ? v.toWellFormed() : v;
+  const open = (v) => {
+    if (Array.isArray(v)) return { keys: null, items: v, built: [] };
+    if (v !== null && typeof v === "object") {
+      const entries = Object.entries(v);
+      return {
+        keys: entries.map(([key]) => key.toWellFormed()),
+        items: entries.map(([, item]) => item),
+        built: []
+      };
+    }
+    return null;
+  };
+  const close = (f) => (
+    // `Object.fromEntries` uses CreateDataProperty, so a literal `__proto__`
+    // key becomes an OWN property. Assigning `out[key] = …` instead invoked
+    // the `Object.prototype.__proto__` SETTER: the key vanished from the
+    // persisted message and the rebuilt object took a tool-controlled
+    // prototype (spec 025 review).
+    f.keys === null ? f.built : Object.fromEntries(f.keys.map((k, i) => [k, f.built[i]]))
+  );
+  const rootFrame = open(root);
+  if (rootFrame === null) return leaf(root);
+  const frames = [rootFrame];
+  for (; ; ) {
+    const frame = frames[frames.length - 1];
+    if (frame.built.length === frame.items.length) {
+      const value = close(frame);
+      frames.pop();
+      if (frames.length === 0) return value;
+      frames[frames.length - 1].built.push(value);
+      continue;
+    }
+    const next = frame.items[frame.built.length];
+    const child = open(next);
+    if (child === null) frame.built.push(leaf(next));
+    else frames.push(child);
+  }
+}
+function toWellFormedDeep(value) {
+  return hasMalformed(value) ? repair(value) : value;
+}
+var MalformedTextError = class extends Error {
+  constructor(path) {
+    super(
+      `malformed UTF-16 at ${path}: a lone surrogate is not text and cannot be persisted \u2014 run toWellFormedDeep() on the value first`
+    );
+    this.path = path;
+    this.name = "MalformedTextError";
+  }
+  path;
+};
+function malformedPath(root, base) {
+  const stack = [{ value: root, path: base }];
+  while (stack.length > 0) {
+    const { value, path } = stack.pop();
+    if (typeof value === "string") {
+      if (!value.isWellFormed()) return path;
+    } else if (Array.isArray(value)) {
+      for (let i = value.length - 1; i >= 0; i--) {
+        stack.push({ value: value[i], path: `${path}[${i}]` });
+      }
+    } else if (value !== null && typeof value === "object") {
+      const entries = Object.entries(value);
+      for (const [key] of entries) if (!key.isWellFormed()) return `${path}.<key>`;
+      for (let i = entries.length - 1; i >= 0; i--) {
+        const entry = entries[i];
+        stack.push({ value: entry[1], path: `${path}.${entry[0]}` });
+      }
+    }
+  }
+  return base;
+}
+function assertWellFormed(value, where) {
+  if (!hasMalformed(value)) return;
+  throw new MalformedTextError(malformedPath(value, where));
+}
+
+export {
+  InvalidScopeError,
+  scopePath,
+  cutAtCodePoint,
+  toWellFormedDeep,
+  MalformedTextError,
+  assertWellFormed
+};
+//# sourceMappingURL=chunk-KPNXPUGR.js.map

package/dist/chunk-KPNXPUGR.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/scope.ts","../src/text.ts"],"sourcesContent":["/**\n * Tenancy scope — the isolation boundary of the whole harness.\n *\n * `{org, uid}` derives from a server-verified token, never from a client\n * payload, and is bound to tool registries by closure at construction time —\n * the model never passes org/uid as parameters.\n *\n * @see docs/architecture.md §6.1, §6.8\n */\nexport interface Scope {\n  /** Organization (tenant) id. */\n  readonly org: string;\n  /** User id within the organization. */\n  readonly uid: string;\n}\n\n/**\n * Thrown by {@link scopePath} when a scope segment could be used for path\n * traversal or key-delimiter injection.\n */\nexport class InvalidScopeError extends Error {\n  constructor(segment: \"org\" | \"uid\", value: string) {\n    super(`Invalid scope ${segment}: ${JSON.stringify(value)}`);\n    this.name = \"InvalidScopeError\";\n  }\n}\n\n/**\n * DECISION: allowed charset for scope segments. The doc (§2) records uneven\n * path-sanitization hardening as a production bug class; the harness therefore\n * validates centrally. Alphanumerics plus `_ - .` (no leading dot) covers real\n * Firebase uids and org slugs while excluding `/`, `..` and whitespace.\n */\nconst SCOPE_SEGMENT = /^[A-Za-z0-9_-][A-Za-z0-9._-]*$/;\n\n/**\n * The single place that builds `tenants/{org}/users/{uid}` — §6.8.\n *\n * A *concept*, not a literal storage path: the Firestore adapter renders it as\n * a collection path, the Postgres adapter as row-level-security predicates\n * (§6). Every store keys its data by this concept so scoped purge and export\n * have one canonical addressing scheme.\n */\nexport function scopePath(scope: Scope): string {\n  if (!SCOPE_SEGMENT.test(scope.org)) throw new InvalidScopeError(\"org\", scope.org);\n  if (!SCOPE_SEGMENT.test(scope.uid)) throw new InvalidScopeError(\"uid\", scope.uid);\n  return `tenants/${scope.org}/users/${scope.uid}`;\n}\n","/**\n * Text safety at the persistence boundary — spec: well-formed-text.\n *\n * A JavaScript string is UTF-16 code units, and everything outside the BMP —\n * emoji, the CJK range — is two of them. Any operation that cuts by index can\n * leave a LONE SURROGATE: half a character, which is not text. It is invalid\n * in `jsonb`, so a store that persists `JSON.stringify(msg)::jsonb` rejects\n * the write and the turn loses every message including the user's.\n */\n\n/**\n * Cuts `text` at `end` code units, moving back one when that would split a\n * surrogate pair.\n *\n * PRECONDITION: `text` is well-formed. This helper does not REPAIR — it only\n * declines to break — so a lone surrogate already present survives the cut.\n * A caller that cannot guarantee its input (spec 025 review: the memory\n * validator now REFUSES what this could hand it) runs `toWellFormedDeep`\n * first.\n *\n * Given that precondition, exactly one case can break, so the check is O(1):\n * a HIGH surrogate at the last included index, whose partner sits just past\n * the cut. A low surrogate there already has its partner included.\n *\n * Grapheme clusters are deliberately NOT preserved — an accent can still be\n * separated from its base letter. That is cosmetic in a string the reader is\n * told was truncated; a lone surrogate is a data-integrity failure.\n */\nexport function cutAtCodePoint(text: string, end: number): string {\n  if (end <= 0) return \"\";\n  const last = text.charCodeAt(end - 1);\n  return text.slice(0, last >= 0xd800 && last <= 0xdbff ? end - 1 : end);\n}\n\n/**\n * True when any string in `value` — including any object KEY — is malformed.\n *\n * ITERATIVE on purpose. The first draft recursed, and a recursive walk blew\n * the stack at ~4,000 levels of nesting while `JSON.stringify` handled the\n * same value: a payload the store would have ACCEPTED made the repair throw\n * (spec 025 review). Detection runs on every turn, so it is the half that must\n * never be the thing that fails.\n */\nfunction hasMalformed(root: unknown): boolean {\n  const stack: unknown[] = [root];\n  while (stack.length > 0) {\n    const value = stack.pop();\n    if (typeof value === \"string\") {\n      if (!value.isWellFormed()) return true;\n    } else if (Array.isArray(value)) {\n      for (const item of value) stack.push(item);\n    } else if (value !== null && typeof value === \"object\") {\n      for (const [key, item] of Object.entries(value)) {\n        // Keys travel into the JSON too, and a malformed one is refused by\n        // `jsonb` exactly like a malformed value — the first draft checked\n        // values only, so `{\"bad\\ud83dkey\": \"fine\"}` sailed through.\n        if (!key.isWellFormed()) return true;\n        stack.push(item);\n      }\n    }\n  }\n  return false;\n}\n\n/**\n * Rebuilds `value` with every string — key and leaf — made well-formed.\n *\n * Wholesale, not selectively: identity is the guarantee for a CLEAN value, and\n * a broken one is being rewritten anyway. The untouched branches keep their\n * bytes, and the cached prefix keys off content rather than object identity.\n */\nfunction repair(root: unknown): unknown {\n  // ITERATIVE, like `hasMalformed` and for the same reason — spec 040 review.\n  // This was the LAST recursive walk over this shape, and it was the one that\n  // mattered: detection was made iterative in spec 025 while repair was left\n  // recursive behind a best-effort `catch`, so a deeply nested MALFORMED value\n  // was detected and then failed to be repaired. The existing depth pin could\n  // not see it because its 50,000-level fixture is clean, so `hasMalformed`\n  // returns false and repair never runs.\n  //\n  // An explicit stack of half-built containers, closed bottom-up. Children are\n  // produced before their parent, so nothing is rebuilt twice.\n  interface Frame {\n    /** Repaired keys, in order — `null` marks an array. */\n    keys: string[] | null;\n    items: readonly unknown[];\n    built: unknown[];\n  }\n\n  const leaf = (v: unknown): unknown => (typeof v === \"string\" ? v.toWellFormed() : v);\n\n  const open = (v: unknown): Frame | null => {\n    if (Array.isArray(v)) return { keys: null, items: v, built: [] };\n    if (v !== null && typeof v === \"object\") {\n      const entries = Object.entries(v);\n      return {\n        keys: entries.map(([key]) => key.toWellFormed()),\n        items: entries.map(([, item]) => item),\n        built: [],\n      };\n    }\n    return null;\n  };\n\n  const close = (f: Frame): unknown =>\n    // `Object.fromEntries` uses CreateDataProperty, so a literal `__proto__`\n    // key becomes an OWN property. Assigning `out[key] = …` instead invoked\n    // the `Object.prototype.__proto__` SETTER: the key vanished from the\n    // persisted message and the rebuilt object took a tool-controlled\n    // prototype (spec 025 review).\n    f.keys === null ? f.built : Object.fromEntries(f.keys.map((k, i) => [k, f.built[i]]));\n\n  const rootFrame = open(root);\n  if (rootFrame === null) return leaf(root);\n\n  const frames: Frame[] = [rootFrame];\n  for (;;) {\n    const frame = frames[frames.length - 1]!;\n    if (frame.built.length === frame.items.length) {\n      const value = close(frame);\n      frames.pop();\n      if (frames.length === 0) return value;\n      frames[frames.length - 1]!.built.push(value);\n      continue;\n    }\n    const next = frame.items[frame.built.length];\n    const child = open(next);\n    if (child === null) frame.built.push(leaf(next));\n    else frames.push(child);\n  }\n}\n\n/**\n * Returns `value` with every string made well-formed, each lone surrogate\n * replaced by U+FFFD — and the SAME REFERENCE when nothing was broken.\n *\n * The identity property is load-bearing rather than an optimization: an\n * under-ceiling tool output must be persisted byte-identical or the cached\n * prefix drifts (spec: tool-output-discipline), and a normalizer that rebuilt\n * every message would drift all of them. Detection allocates nothing beyond a\n * work stack; only an already-broken value is rebuilt.\n *\n * ⚠ Do NOT replace this with a one-pass check on the serialized form.\n * `JSON.stringify` has been well-formed since ES2019: it escapes a lone\n * surrogate as `\\ud83d`, so `JSON.stringify(v).isWellFormed()` is ALWAYS true\n * and detects nothing. Normalizing that output does not help either — the\n * escape survives, and the store still rejects it. Only the source string can\n * be repaired.\n *\n * BOTH halves are iterative as of spec 040. Detection was made so in spec 025;\n * repair was left recursive behind each caller's best-effort `catch`, which\n * meant a deeply nested MALFORMED value was detected and then not repaired —\n * invisible to the depth pin of the day, whose fixture is clean and therefore\n * never reaches repair at all. Callers still treat repair as best-effort, and\n * that is now belt-and-braces rather than the load-bearing mitigation it was.\n */\nexport function toWellFormedDeep<T>(value: T): T {\n  return hasMalformed(value) ? (repair(value) as T) : value;\n}\n\n/**\n * A store refused a write because a string in it was not text — spec 040.\n *\n * Its own class so a bulk writer can catch this and nothing else: a migration\n * wants to skip or repair the one bad row, not swallow a connection failure\n * alongside it.\n *\n * The message names the PATH and never the content. A lone surrogate prints\n * as a replacement box and the string around it is, in the case that drove\n * this, clinical text — neither belongs in a log line.\n */\nexport class MalformedTextError extends Error {\n  constructor(readonly path: string) {\n    super(\n      `malformed UTF-16 at ${path}: a lone surrogate is not text and cannot be ` +\n        `persisted — run toWellFormedDeep() on the value first`,\n    );\n    this.name = \"MalformedTextError\";\n  }\n}\n\n/**\n * Locates a malformed string, as a readable path. Runs ONLY after\n * {@link hasMalformed} has already said there is one, so the cost of carrying\n * paths is paid on the failing write and never on the hot one.\n *\n * ITERATIVE, for the reason {@link hasMalformed} is — spec 040's own review.\n * The first version recursed one frame per level of nesting and threw\n * `RangeError` instead of {@link MalformedTextError} on a value `JSON.stringify`\n * handles, which is the exact defect spec 025 removed from detection and this\n * function reintroduced beside it. A caller writing\n * `catch (e) { if (e instanceof MalformedTextError) … }` — the usage this class\n * exists to support — would not have caught it.\n *\n * Depth-first, left to right, with an object's KEYS all checked before any of\n * its values are descended into. So the path is the first offender in that\n * order, not an arbitrary one.\n */\nfunction malformedPath(root: unknown, base: string): string {\n  const stack: { value: unknown; path: string }[] = [{ value: root, path: base }];\n  while (stack.length > 0) {\n    const { value, path } = stack.pop()!;\n    if (typeof value === \"string\") {\n      if (!value.isWellFormed()) return path;\n    } else if (Array.isArray(value)) {\n      // Pushed in reverse so `pop` yields them in order.\n      for (let i = value.length - 1; i >= 0; i--) {\n        stack.push({ value: value[i], path: `${path}[${i}]` });\n      }\n    } else if (value !== null && typeof value === \"object\") {\n      const entries = Object.entries(value);\n      // A malformed KEY is reported as `<key>` rather than by its own text —\n      // the text is what cannot be printed.\n      for (const [key] of entries) if (!key.isWellFormed()) return `${path}.<key>`;\n      for (let i = entries.length - 1; i >= 0; i--) {\n        const entry = entries[i]!;\n        stack.push({ value: entry[1], path: `${path}.${entry[0]}` });\n      }\n    }\n  }\n  return base;\n}\n\n/**\n * Throws {@link MalformedTextError} when any string in `value` — object keys\n * included — is not well-formed UTF-16.\n *\n * The guard every store calls at its write boundary, so that the adapters\n * AGREE (spec 040). They used to diverge: `jsonb` refuses a lone surrogate so\n * the Postgres adapters failed the write, while the in-memory references kept\n * it — and both contracts said \"do not rely on either behaviour\", which is not\n * a contract. `runTurn` repairs on the way in, but only BEST-EFFORT (its catch\n * keeps the unrepaired message), and a product writing to a store directly —\n * a migration, a backfill, a replay — has no such pass at all.\n *\n * Refusing rather than repairing here is deliberate. A store that silently\n * rewrites the bytes of a record kept for years is worse than one that\n * refuses, and since the repair is best-effort by design an `append` that\n * repaired would still not be a guarantee.\n *\n * `where` labels the value for the message — typically the parameter name and\n * index, e.g. `entries[3]`.\n */\nexport function assertWellFormed(value: unknown, where: string): void {\n  // Cheap detection first: the clean path allocates nothing beyond the work\n  // stack and never builds a path string.\n  if (!hasMalformed(value)) return;\n  throw new MalformedTextError(malformedPath(value, where));\n}\n"],"mappings":"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","names":[]}