@noy-db/hub 0.7.1-pre.0 → 0.8.0

package/dist/{chunk-7O3Y4PPD.js → chunk-37EPTBBR.js}

@@ -36,21 +36,59 @@ var DecryptionError = class extends NoydbError {
     this.name = "DecryptionError";
   }
 };
+var MissingEnvelopeBodyError = class extends NoydbError {
+  /** The operation that required a sealed body, e.g. `'openEnvelopeJson'`. */
+  where;
+  constructor(where) {
+    super(
+      "ENVELOPE_BODY_MISSING",
+      `${where}: this envelope carries no sealed body (_iv/_data absent). An enclave capsule cannot open a row written by an exclave capsule.`
+    );
+    this.name = "MissingEnvelopeBodyError";
+    this.where = where;
+  }
+};
 var TamperedError = class extends NoydbError {
   /**
-   * Why the tag check failed, when the enclave could tell (#1103).
+   * Evidence the thrower held BEFORE decrypting, when it held any. Additive
+   * (#1103 pattern): the throw and the class are unchanged, so
+   * `catch (e) { if (e instanceof TamperedError) … }` keeps working; callers
+   * that want to tell a migration or a missing grant from a breach read this.
    *
-   * `'unbound-legacy-format'` — the body opens under an EMPTY AAD, so it was
-   * sealed before identity binding (#1041) and this is a format transition, not
-   * an attack. Positive evidence, not a guess: producing a body that decrypts
-   * under this DEK requires the DEK, which an untrusted store does not hold.
+   * - `'unbound-legacy-format'` — the body opens under an EMPTY AAD, so it was
+   *   sealed before identity binding (#1041): a format transition, not an
+   *   attack. Positive evidence: producing a body that decrypts under this DEK
+   *   requires the DEK, which an untrusted store does not hold. (#1103)
+   * - `'key-absent'` — this keyring holds no DEK for a collection that already
+   *   has records, and the DEK cannot be back-filled (wrapping needs the
+   *   grantee's secret, which the vault never stores). Thrown by the DEK
+   *   resolver instead of minting a key that would decrypt nothing and
+   *   resurface as a bare AEAD failure — the #1288 misdiagnosis. Reserved
+   *   collections (`_periods`, …) take this path; user collections throw
+   *   `NoAccessError` (#1004/#1010).
+   * - `'generation-mismatch'` — reserved for "the artefact was sealed at a
+   *   generation this reader cannot compute". **Not emitted by this build**:
+   *   hub reads no generation stamp off any envelope — `NOYDB_ENVELOPE_GENERATION`
+   *   is an exported constant, and the stamp a bundle carries is manifest data
+   *   a reader never branches on (ADR 0003). The one generation fact hub can
+   *   establish from the bytes — "opens under an empty AAD" — is already
+   *   `'unbound-legacy-format'`. Absence of a stamp never reads as
+   *   generation 1 (`docs/ENVELOPE-GENERATION.md`).
+   * - `'foreign-stamp'` — reserved for "this vault's DEK was asked to open a
+   *   body identity-bound to ANOTHER vault". **Not emitted by this build**:
+   *   nothing in hub can tell that apart from another vault's compartment
+   *   merely being present, which in a multi-vault bundle is normal
+   *   (klum `extractCrossVaultPartition`).
    *
-   * Absent — no benign explanation was found. Treat as the security alert this
-   * error has always been.
+   * Both reserved values are declared so consumers can type against them; a
+   * build that starts emitting either will say so in its CHANGELOG.
    *
-   * The field is additive and the throw is unchanged, so
-   * `catch (e) { if (e instanceof TamperedError) … }` keeps working; callers
-   * that want to tell a migration from a breach can now read this.
+   * Absent — no evidence; the security alert.
+   *
+   * ⚠️ `reason` is hub's IN-PROCESS report and may be branched on. A
+   * generation or origin stamp read out of an untrusted manifest may NOT — it
+   * is store-supplied data, not evidence (klum ADR 0003). If you are holding
+   * a stamp and not this error, you are holding a claim.
    */
   reason;
   constructor(message = "Data integrity check failed \u2014 record may have been tampered with", reason) {
@@ -268,7 +306,16 @@ var PeriodClosedError = class extends NoydbError {
   periodName;
   endDate;
   recordTs;
-  constructor(periodName, endDate, recordTs) {
+  /**
+   * #1455 — the business-date field the guard compared, when the period
+   * declares one. Absent on the envelope-`_ts` (no `dateField`) path.
+   * Structured so a consumer can render the refusal without parsing
+   * `recordTs`'s composed `"incoming[cycle]=2026-06"` form.
+   */
+  dateField;
+  /** #1455 — which side of the write tripped the seal. */
+  side;
+  constructor(periodName, endDate, recordTs, detail) {
     super(
       "PERIOD_CLOSED",
       `Cannot modify record (last written ${recordTs}) \u2014 sealed by closed period "${periodName}" (endDate: ${endDate}). Post a compensating entry in a new period instead.`
@@ -277,6 +324,21 @@ var PeriodClosedError = class extends NoydbError {
     this.periodName = periodName;
     this.endDate = endDate;
     this.recordTs = recordTs;
+    this.dateField = detail?.dateField;
+    this.side = detail?.side;
+  }
+};
+var PeriodChainError = class extends NoydbError {
+  periodName;
+  partition;
+  constructor(periodName, why, partition) {
+    super(
+      "PERIOD_CHAIN_BROKEN",
+      `Period "${periodName}"${partition && partition.length ? ` (partition ${JSON.stringify(partition)})` : ""} does not verify against its predecessor: ${why}. The _periods record set has been altered outside the period engine; refusing to trust it.`
+    );
+    this.name = "PeriodChainError";
+    this.periodName = periodName;
+    this.partition = partition;
   }
 };
 var RecordLockedError = class extends NoydbError {
@@ -567,6 +629,12 @@ var ValidationError = class extends NoydbError {
     this.name = "ValidationError";
   }
 };
+var UnsafePatternError = class extends NoydbError {
+  constructor(message) {
+    super("UNSAFE_PATTERN", message);
+    this.name = "UnsafePatternError";
+  }
+};
 var SchemaValidationError = class extends NoydbError {
   issues;
   direction;
@@ -620,10 +688,10 @@ var GroupCardinalityError = class extends NoydbError {
   cardinality;
   /** The cap that was exceeded. */
   maxGroups;
-  constructor(field, cardinality, maxGroups) {
+  constructor(field, cardinality, maxGroups, surface = "query") {
     super(
       "GROUP_CARDINALITY",
-      `.groupBy("${field}") produced ${cardinality} distinct groups, exceeding the ${maxGroups}-group ceiling. This is almost always a query mistake \u2014 grouping on a high-uniqueness field like "id" or "createdAt" produces one bucket per record. Narrow the query with .where() before grouping, or group on a lower-cardinality field (status, category, clientId). If you genuinely need high-cardinality grouping, file an issue with your use case.`
+      surface === "scan" ? `scan().groupBy("${field}") reached ${cardinality} distinct groups, exceeding the declared { maxGroups: ${maxGroups} } budget. A grouped scan holds one reducer state per group in memory, so this is a refusal, never a truncation \u2014 the rows you would have got back are incomplete by definition. Either narrow the scan with .where() before .groupBy(), group on a lower-cardinality key, or raise the budget deliberately with .groupBy(key, { maxGroups: N }) once you have priced N reducer states (an exact median/percentile or a countDistinct holds O(values) per group; { approx: true } bounds it).` : `.groupBy("${field}") produced ${cardinality} distinct groups, exceeding the ${maxGroups}-group ceiling. This is almost always a query mistake \u2014 grouping on a high-uniqueness field like "id" or "createdAt" produces one bucket per record. Narrow the query with .where() before grouping, or group on a lower-cardinality field (status, category, clientId). If you genuinely need high-cardinality grouping, file an issue with your use case.`
     );
     this.name = "GroupCardinalityError";
     this.field = field;
@@ -631,19 +699,48 @@ var GroupCardinalityError = class extends NoydbError {
     this.maxGroups = maxGroups;
   }
 };
+var TraversalCycleError = class extends NoydbError {
+  /** The declared self-ref field being traversed. */
+  field;
+  /** The path that closed on itself, with the re-entered id repeated last. */
+  cycle;
+  constructor(opts) {
+    super(
+      "TRAVERSAL_CYCLE",
+      `.traverse("${opts.field}") reached a cycle: ${opts.cycle.join(" \u2192 ")}. The default { onCycle: 'stop' } prunes the repeated node and finishes the walk; this query asked for { onCycle: 'throw' }. Fix the parent chain, or drop back to 'stop' if cycles are expected in this data.`
+    );
+    this.name = "TraversalCycleError";
+    this.field = opts.field;
+    this.cycle = opts.cycle;
+  }
+};
 var IndexRequiredError = class extends NoydbError {
   collection;
   touchedFields;
   missingFields;
+  /**
+   * Why the index could not serve the query, when it is NOT "a field is
+   * unindexed" (#1407).
+   *
+   * ⚠️ The default message names missing fields, and that sentence is FALSE
+   * for a refusal on an indexed field — a `where(f,'==',null)` in lazy mode is
+   * refused because the persisted index never holds nullish values, not
+   * because `f` lacks an index. Telling that caller to "declare an index on
+   * each field" sends them to fix something that is already correct, which is
+   * the same defect #1430 fixed in `WeakSecretError`: advice describing rules
+   * that do not apply here.
+   */
+  reason;
   constructor(args) {
     super(
       "INDEX_REQUIRED",
-      `Collection "${args.collection}": query references unindexed fields in lazy mode (missing: ${args.missingFields.join(", ")}). Declare an index on each field, or use collection.scan() for non-indexed iteration.`
+      args.reason !== void 0 ? `Collection "${args.collection}": ${args.reason}` : `Collection "${args.collection}": query references unindexed fields in lazy mode (missing: ${args.missingFields.join(", ")}). Declare an index on each field, or use collection.scan() for non-indexed iteration.`
     );
     this.name = "IndexRequiredError";
     this.collection = args.collection;
     this.touchedFields = [...args.touchedFields];
     this.missingFields = [...args.missingFields];
+    this.reason = args.reason;
   }
 };
 var UniqueConstraintError = class extends NoydbError {
@@ -699,6 +796,21 @@ var PersistedIndexCompensationError = class extends NoydbError {
     this.cause = cause;
   }
 };
+var QueryExtensionMissingError = class extends NoydbError {
+  /** The method that was called, e.g. `'join'`. */
+  method;
+  /** The subpath whose import supplies it, e.g. `'@noy-db/hub/query/relate'`. */
+  subpath;
+  constructor(method, subpath) {
+    super(
+      "QUERY_EXTENSION_MISSING",
+      `Query.${method}() is not loaded. It ships in ${subpath}; add \`import '${subpath}'\` once, anywhere in your app's entry, and the method (and its types) attach to every Query. The Find group \u2014 where/or/and/filter/orderBy/limit/offset/page/after/first/toArray/count/exists/ids/toPlan \u2014 needs no import.`
+    );
+    this.name = "QueryExtensionMissingError";
+    this.method = method;
+    this.subpath = subpath;
+  }
+};
 var FieldNotQueryableError = class extends NoydbError {
   field;
   constructor(field) {
@@ -710,6 +822,19 @@ var FieldNotQueryableError = class extends NoydbError {
     this.field = field;
   }
 };
+var CollectionNotHydratedError = class extends NoydbError {
+  collection;
+  terminal;
+  constructor(collection, terminal, label = collection) {
+    super(
+      "COLLECTION_NOT_HYDRATED",
+      `Collection "${label}": ${terminal}() cannot answer \u2014 the collection has not been loaded yet, so its in-memory snapshot is empty by absence, not by content. Await the terminal (\`await collection.query().${terminal}()\`), or call \`await collection.list()\` / \`await collection.get(id)\` before reading it synchronously. An unloaded collection is not an empty one.`
+    );
+    this.name = "CollectionNotHydratedError";
+    this.collection = collection;
+    this.terminal = terminal;
+  }
+};
 var PodIntegrityError = class extends NoydbError {
   constructor(message) {
     super("BUNDLE_INTEGRITY", `.noydb bundle integrity check failed: ${message}`);
@@ -1100,6 +1225,12 @@ var JoinTooLargeError = class extends NoydbError {
   leftRows;
   rightRows;
   maxRows;
+  /**
+   * Which count tripped the ceiling. `'output'` is #1339's addition: a
+   * declared non-equi `.joinOn()` is many-to-many, so it can exceed the
+   * ceiling with both SIDES comfortably under it — the produced row count is
+   * the only thing standing between a theta join and a hang.
+   */
   side;
   constructor(opts) {
     super("JOIN_TOO_LARGE", opts.message);
@@ -1518,7 +1649,7 @@ var PolicyDeniedError = class extends NoydbError {
   }
 };
 var RecoveryNotEnrolledError = class extends NoydbError {
-  constructor(message = 'Recovery profile not enrolled. Pass `recovery: [{ profile: "paper", codes: 10 }]` to `createNoydb()`, or set `policy.gates["recover-secret"].enabled = false` to opt out of recovery (secret loss = data loss). See https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/session-tiers.md.') {
+  constructor(message = 'Recovery profile not enrolled. Pass `recovery: [{ profile: "paper", codes: 10 }]` to `createNoydb()`, or set `policy.gates["recover-secret"].enabled = false` to opt out of recovery (secret loss = data loss). See https://github.com/noy-db/docs/blob/main/content/docs/services/session-tiers.md.') {
     super("RECOVERY_NOT_ENROLLED", message);
     this.name = "RecoveryNotEnrolledError";
   }
@@ -1615,6 +1746,7 @@ export {
   DebugPlaintextError,
   DebugReservedFieldError,
   DecryptionError,
+  MissingEnvelopeBodyError,
   TamperedError,
   InvalidKeyError,
   KeyringCorruptError,
@@ -1636,6 +1768,7 @@ export {
   PrivilegeEscalationError,
   ReservedVaultNameError,
   PeriodClosedError,
+  PeriodChainError,
   RecordLockedError,
   FieldFrozenError,
   IllegalTransitionError,
@@ -1663,6 +1796,7 @@ export {
   NetworkError,
   NotFoundError,
   ValidationError,
+  UnsafePatternError,
   SchemaValidationError,
   SchemaUpdateError,
   NonAdditiveSchemaChangeError,
@@ -1671,12 +1805,15 @@ export {
   MigrationRequiredError,
   QuiesceTimeoutError,
   GroupCardinalityError,
+  TraversalCycleError,
   IndexRequiredError,
   UniqueConstraintError,
   UnsupportedIndexOptionError,
   IndexWriteFailureError,
   PersistedIndexCompensationError,
+  QueryExtensionMissingError,
   FieldNotQueryableError,
+  CollectionNotHydratedError,
   PodIntegrityError,
   PodHeaderVerificationError,
   PodSealMismatchError,
@@ -1761,4 +1898,4 @@ export {
   ClassifiedRotationError,
   SatelliteConfigError
 };
-//# sourceMappingURL=chunk-7O3Y4PPD.js.map
+//# sourceMappingURL=chunk-37EPTBBR.js.map