@noy-db/hub 0.4.0-pre.9 → 0.5.0

package/dist/chunk-RQILGK3N.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/with-commit/sequence/active.ts","../src/with-commit/sequence/strategy.ts","../src/with-commit/sequence/index.ts"],"sourcesContent":["/**\n * Enable the atomic-sequence capability.\n * Pass to `createNoydb({ sequenceStrategy: withSequence() })` to make\n * `vault.sequence('name').next()` / `.peek()` / `.seedTo()` live. The\n * {@link SequenceStore} CAS engine is statically imported here, so it is pulled\n * into the bundle only when `withSequence()` is referenced (the floor never\n * imports it).\n */\nimport type { SequenceStrategy } from './strategy.js'\nimport { SequenceStore } from './index.js'\n\nexport function withSequence(): SequenceStrategy {\n  return {\n    createStore(opts) {\n      return new SequenceStore(opts)\n    },\n  }\n}\n","/**\n * Sequence capability strategy — the single on-demand factory the vault routes\n * `vault.sequence()` through to build its atomic-CAS {@link SequenceStore}. The\n * active engine ({@link withSequence}) constructs the real store (kept out of\n * the floor bundle — the store class is reached only via the opt-in\n * `active.ts` chunk); {@link NO_SEQUENCE} throws. The vault always assembles the\n * per-call {@link SequenceStoreOptions} and delegates here, so an un-opted-in\n * caller hits `NO_SEQUENCE`'s throw at `vault.sequence()`.\n *\n * Note: `vault.sequence()` is synchronous, so the factory is a plain (sync)\n * constructor — the engine is tree-shaken by reachability (only `withSequence()`\n * pulls `active.ts`, which statically imports the store), not by a dynamic\n * import. Deferred-numbering series (`withDeferredNumbering`) are a distinct\n * capability and are NOT routed through this strategy.\n * @internal\n */\nimport type { SequenceStore, SequenceStoreOptions } from './index.js'\nimport { SequenceNotEnabledError } from '../../kernel/errors.js'\n\nexport interface SequenceStrategy {\n  createStore(opts: SequenceStoreOptions): SequenceStore\n}\n\n/**\n * No-op stub — the floor default. The capability factory throws\n * {@link SequenceNotEnabledError}; opt in with `sequenceStrategy: withSequence()`\n * in createNoydb. @internal\n */\nexport const NO_SEQUENCE: SequenceStrategy = {\n  createStore(): SequenceStore {\n    throw new SequenceNotEnabledError()\n  },\n}\n","/**\n * Atomic sequence primitive — online-coordinated gap-free numbering.\n *\n * `vault.sequence('invoice-2026').next()` returns 1, 2, 3, … with no\n * gaps and no duplicates, even under concurrent callers. Each named\n * sequence is an independent counter record at `_sequences/<name>`,\n * incremented with an optimistic compare-and-swap retry loop — the same\n * proven pattern as the ledger head (`history/ledger/store.ts`).\n *\n * **Explicitly online-only.** Gap-free numbering requires single-authority\n * serialization, which an offline / non-CAS store cannot provide. `next()`\n * throws {@link SequenceOfflineError} unless the backing store advertises\n * `capabilities.casAtomic`. This is a deliberate, honest wall — an offline\n * writer cannot safely allocate a global sequence number.\n *\n * Note on \"gap-free\": the *sequence* is gap-free (each `next()` yields a\n * unique, +1 value). If a caller discards a value without using it, that\n * is a gap in *usage*, not in the sequence — assign each `next()` result\n * to its record in the same operation.\n */\n\nimport type { NoydbStore, EncryptedEnvelope } from '../../kernel/types.js'\nimport { NOYDB_FORMAT_VERSION } from '../../kernel/types.js'\nimport { encrypt, openEnvelopeJson, type EnclaveKey } from '../../kernel/enclave/index.js'\nimport type { ConflictError} from '../../kernel/errors.js';\nimport { isConflictError, SequenceContentionError, SequenceOfflineError, ValidationError } from '../../kernel/errors.js'\n\n// Capability opt-in seam (S4): `vault.sequence()` builds its CAS store through\n// the sequenceStrategy, so it throws SequenceNotEnabledError unless opted in.\nexport { withSequence } from './active.js'\nexport { NO_SEQUENCE, type SequenceStrategy } from './strategy.js'\nexport { SequenceNotEnabledError } from '../../kernel/errors.js'\n\nexport const SEQUENCE_COLLECTION = '_sequences'\n// A sequence is a single hot CAS row — higher contention than a ledger\n// append. A larger budget + jittered backoff absorbs moderate concurrency;\n// a genuine burst beyond this surfaces SequenceContentionError so the\n// caller can retry / queue (the honest online-only contract).\nconst MAX_NEXT_ATTEMPTS = 16\n\ninterface SequenceState {\n  value: number\n}\n\n/** Options for `SequenceHandle.next`. Deferred-numbering series use `for`; the CAS counter ignores all of these. */\nexport interface NextOptions {\n  /** Deferred mode: the record id to number. Ignored by the CAS counter. */\n  readonly for?: string\n  /** Deferred mode: reject after this many ms if still unsealed (reserved; not yet enforced in this slice). */\n  readonly timeoutMs?: number\n}\n\n/**\n * Partitioning for a CAS sequence. A partitioned sequence is an\n * independent counter scoped to one tuple of values — e.g.\n * `sequence('invoice', { partition: [2026, 'EU'] })` numbers EU-2026 invoices\n * separately from `[2026, 'US']` and from the bare `invoice` series.\n *\n * Partition components are URI-encoded (so `/`, null bytes and other\n * separators in a value can never collide with the structural separators) and\n * `'/'`-joined, then appended to the series with a null-byte (`\\x00`)\n * separator. The null byte is illegal in a plain series name, which guarantees\n * a partitioned key is always disjoint from any unpartitioned series.\n */\nexport interface SequenceOptions {\n  /** Partition tuple. Each component is URI-encoded and `'/'`-joined. */\n  readonly partition?: readonly (string | number)[]\n  /**\n   * Render template for the serial string. When set, `vault.sequence`\n   * returns a {@link FormattedSequenceHandle} whose `next()` resolves to\n   * `{ serial, formatted }`. Tokens:\n   * - `{seq}` — the allocated integer\n   * - `{seq:0N}` — zero-padded to width N (e.g. `{seq:04}` → `0001`)\n   * - `{partition.i}` — the i-th `partition` component (original value)\n   *\n   * Any other token, or a `{partition.i}` index beyond the supplied\n   * `partition`, throws `ValidationError` at `vault.sequence()` construction.\n   * Per-partition reset is inherent: a new partition tuple starts at 1.\n   */\n  readonly format?: string\n}\n\n/**\n * A formatted sequence handle. Identical to {@link SequenceHandle}\n * except `next()` also returns the rendered `formatted` string. `peek()` /\n * `seedTo()` operate on the underlying integer counter, unchanged.\n */\nexport interface FormattedSequenceHandle {\n  /** Allocate the next value and return it with its rendered serial string. */\n  next(opts?: NextOptions): Promise<{ serial: number; formatted: string }>\n  /** Read the current integer value without allocating. Returns 0 if never used. */\n  peek(): Promise<number>\n  /** Set-if-greater on the underlying integer counter. See {@link SequenceHandle.seedTo}. */\n  seedTo(n: number): Promise<void>\n}\n\n// Matches a single `{...}` token with no nested braces.\nconst SEQ_FORMAT_TOKEN = /\\{([^{}]*)\\}/g\nconst SEQ_PAD_TOKEN = /^seq:0(\\d+)$/\nconst SEQ_PARTITION_TOKEN = /^partition\\.(\\d+)$/\n\n/**\n * Validate a sequence `format` against the supplied partition and return a\n * pure `(serial) => string` renderer. Eager validation: every token is\n * checked now, so a bad pattern throws `ValidationError` at construction —\n * never at `next()` time.\n */\nexport function compileSequenceFormat(\n  format: string,\n  series: string,\n  partition: readonly (string | number)[] | undefined,\n): (serial: number) => string {\n  const parts = partition ?? []\n  for (const m of format.matchAll(SEQ_FORMAT_TOKEN)) {\n    const token = m[1] ?? ''\n    if (token === 'seq') continue\n    if (SEQ_PAD_TOKEN.test(token)) continue\n    const partMatch = SEQ_PARTITION_TOKEN.exec(token)\n    if (partMatch) {\n      const idx = Number(partMatch[1])\n      if (idx >= parts.length) {\n        throw new ValidationError(\n          `sequence(\"${series}\"): format token \"{${token}}\" references partition index ${idx}, ` +\n            `but only ${parts.length} partition component(s) were supplied.`,\n        )\n      }\n      continue\n    }\n    throw new ValidationError(\n      `sequence(\"${series}\"): format contains unknown token \"{${token}}\". ` +\n        `Accepted tokens: {seq}, {seq:0N}, {partition.i}.`,\n    )\n  }\n  return (serial: number): string =>\n    format.replace(SEQ_FORMAT_TOKEN, (full, token: string) => {\n      if (token === 'seq') return String(serial)\n      const padMatch = SEQ_PAD_TOKEN.exec(token)\n      if (padMatch) return String(serial).padStart(Number(padMatch[1]), '0')\n      const partMatch = SEQ_PARTITION_TOKEN.exec(token)\n      if (partMatch) return String(parts[Number(partMatch[1])])\n      return full // unreachable — validated above\n    })\n}\n\n/**\n * Resolve the CAS storage key for a (series, partition) pair.\n *\n * With no partition the key is `series` verbatim. With a partition the key is\n * `${series}\\x00${parts}` where `parts` is each component passed through\n * `encodeURIComponent(String(part))` and `'/'`-joined. The null-byte separator\n * is illegal in a plain series name, so partitioned keys never collide with\n * unpartitioned ones; URI-encoding keeps any component containing `/` distinct\n * from a multi-component partition.\n *\n * @throws {ValidationError} if any partition component is empty after `String()`\n *   or is a non-finite number (`NaN`, `±Infinity`).\n */\nexport function resolveSequenceKey(series: string, opts?: SequenceOptions): string {\n  const partition = opts?.partition\n  if (!partition || partition.length === 0) return series\n  const parts = partition.map((p) => {\n    if (typeof p === 'number' && !Number.isFinite(p)) {\n      throw new ValidationError(`sequence partition component must be a finite number, got ${p}`)\n    }\n    const s = String(p)\n    if (s === '') {\n      throw new ValidationError('sequence partition component must not be empty')\n    }\n    return encodeURIComponent(s)\n  })\n  return `${series}\\x00${parts.join('/')}`\n}\n\nexport interface SequenceHandle {\n  /** Atomically allocate and return the next value (1, 2, 3, …). Deferred series resolve at the next pass. */\n  next(opts?: NextOptions): Promise<number>\n  /** Read the current value without allocating. Returns 0 if never used. */\n  peek(): Promise<number>\n  /**\n   * Set-if-greater: advance the counter to at least `n`. A no-op if the\n   * current value is already `>= n` (so it never rewinds), and `seedTo(0)` is\n   * a no-op. Idempotent and CAS-safe under concurrent `next()` / `seedTo()`.\n   *\n   * Use after a bundle / CSV import to fast-forward the counter past the\n   * highest imported serial, so subsequent `next()` calls cannot re-use a\n   * number that is already on a record.\n   *\n   * Online-only: throws {@link SequenceOfflineError} on a non-CAS store.\n   */\n  seedTo(n: number): Promise<void>\n}\n\nasync function sleepBackoff(attempt: number): Promise<void> {\n  // Exponential backoff with full jitter to break the thundering herd\n  // when many writers contend on the same counter row.\n  const ceil = Math.min(2 ** attempt, 32)\n  const ms = Math.floor(Math.random() * ceil)\n  await new Promise((r) => setTimeout(r, ms))\n}\n\n/** Per-call context the vault assembles to build a {@link SequenceStore}. */\nexport interface SequenceStoreOptions {\n  adapter: NoydbStore\n  vault: string\n  encrypted: boolean\n  getDEK: (collectionName: string) => Promise<EnclaveKey>\n  actor: string\n}\n\nexport class SequenceStore {\n  private readonly adapter: NoydbStore\n  private readonly vault: string\n  private readonly encrypted: boolean\n  private readonly getDEK: (collectionName: string) => Promise<EnclaveKey>\n  private readonly actor: string\n  /**\n   * Memoized DEK promise. The `_sequences` collection DEK is created on\n   * first access; without sharing one promise, a burst of concurrent\n   * `next()` calls would each trigger DEK creation and diverge (one\n   * writer's ciphertext unreadable by another). One shared promise → one\n   * DEK.\n   */\n  private dekPromise: Promise<EnclaveKey> | null = null\n\n  constructor(opts: SequenceStoreOptions) {\n    this.adapter = opts.adapter\n    this.vault = opts.vault\n    this.encrypted = opts.encrypted\n    this.getDEK = opts.getDEK\n    this.actor = opts.actor\n  }\n\n  /** A handle bound to one sequence name. */\n  handle(name: string): SequenceHandle {\n    return {\n      next: () => this.next(name),\n      peek: () => this.peek(name),\n      seedTo: (n) => this.seedTo(name, n),\n    }\n  }\n\n  private assertOnline(): void {\n    if (this.adapter.capabilities?.casAtomic !== true) {\n      throw new SequenceOfflineError()\n    }\n  }\n\n  private dek(): Promise<EnclaveKey> {\n    if (!this.dekPromise) this.dekPromise = this.getDEK(SEQUENCE_COLLECTION)\n    return this.dekPromise\n  }\n\n  private async read(name: string): Promise<{ env: EncryptedEnvelope | null; value: number }> {\n    const env = await this.adapter.get(this.vault, SEQUENCE_COLLECTION, name)\n    if (!env) return { env: null, value: 0 }\n    const json = this.encrypted ? await openEnvelopeJson(env, await this.dek()) : env._data\n    const state = JSON.parse(json) as SequenceState\n    return { env, value: state.value }\n  }\n\n  private async encryptState(state: SequenceState, version: number): Promise<EncryptedEnvelope> {\n    const json = JSON.stringify(state)\n    if (!this.encrypted) {\n      return { _noydb: NOYDB_FORMAT_VERSION, _v: version, _ts: new Date().toISOString(), _iv: '', _data: json, _by: this.actor }\n    }\n    const { iv, data } = await encrypt(json, await this.dek())\n    return { _noydb: NOYDB_FORMAT_VERSION, _v: version, _ts: new Date().toISOString(), _iv: iv, _data: data, _by: this.actor }\n  }\n\n  async peek(name: string): Promise<number> {\n    return (await this.read(name)).value\n  }\n\n  async next(name: string): Promise<number> {\n    this.assertOnline()\n    let lastConflict: ConflictError | undefined\n    for (let attempt = 0; attempt < MAX_NEXT_ATTEMPTS; attempt++) {\n      const { env, value } = await this.read(name)\n      const nextValue = value + 1\n      const expectedVersion = env?._v ?? 0 // 0 ≡ \"must not yet exist\" (create)\n      const envelope = await this.encryptState({ value: nextValue }, expectedVersion + 1)\n      try {\n        await this.adapter.put(this.vault, SEQUENCE_COLLECTION, name, envelope, expectedVersion)\n        return nextValue\n      } catch (err) {\n        if (isConflictError(err)) {\n          lastConflict = err\n          if (attempt < MAX_NEXT_ATTEMPTS - 1) await sleepBackoff(attempt)\n          continue\n        }\n        throw err\n      }\n    }\n    void lastConflict\n    throw new SequenceContentionError(name, MAX_NEXT_ATTEMPTS)\n  }\n\n  async seedTo(name: string, n: number): Promise<void> {\n    this.assertOnline()\n    if (n <= 0) return // set-if-greater: 0 (and any non-positive seed) is a no-op\n    let lastConflict: ConflictError | undefined\n    for (let attempt = 0; attempt < MAX_NEXT_ATTEMPTS; attempt++) {\n      const { env, value } = await this.read(name)\n      if (value >= n) return // already at or past the floor — no write, idempotent\n      const expectedVersion = env?._v ?? 0 // 0 ≡ \"must not yet exist\" (create)\n      const envelope = await this.encryptState({ value: n }, expectedVersion + 1)\n      try {\n        await this.adapter.put(this.vault, SEQUENCE_COLLECTION, name, envelope, expectedVersion)\n        return\n      } catch (err) {\n        if (isConflictError(err)) {\n          lastConflict = err\n          if (attempt < MAX_NEXT_ATTEMPTS - 1) await sleepBackoff(attempt)\n          continue\n        }\n        throw err\n      }\n    }\n    void lastConflict\n    throw new SequenceContentionError(name, MAX_NEXT_ATTEMPTS)\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-EZNTORXE.js → chunk-SBGXQK5I.js}

@@ -1,6 +1,6 @@
 import {
   ValidationError
-} from "./chunk-QZWTRENR.js";
+} from "./chunk-AR5D76T2.js";
 
 // src/with-audit/periods/window.ts
 var PERIODS_COLLECTION = "_periods";
@@ -21,4 +21,4 @@ export {
   PERIOD_TARGET_PURGES_COLLECTION,
   periodExclusiveUpperBound
 };
-//# sourceMappingURL=chunk-EZNTORXE.js.map
+//# sourceMappingURL=chunk-SBGXQK5I.js.map

package/dist/chunk-SBGXQK5I.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/with-audit/periods/window.ts"],"sourcesContent":["/**\n * Pure period-window primitives — the reserved collection names and the\n * exclusive-upper-bound computation shared by freeze (#604), archive (#613),\n * target-purge (#615) and the period-scoped sync pull (#807).\n *\n * Deliberately dependency-light (kernel errors only): the sync engine\n * (`with-sync/period-scope.ts`) imports THIS module, not\n * `periods.ts`, so a period-scoped pull never drags the ledger hash-chain\n * machinery (`sha256Hex`/`canonicalJson`) into a bundle that opted out of\n * the periods service.\n */\nimport { ValidationError } from '../../kernel/errors.js'\n\n/** The reserved collection name holding closed-period metadata. */\nexport const PERIODS_COLLECTION = '_periods'\n\n/** Sibling of {@link PERIODS_COLLECTION} holding freeze companions (#604). */\nexport const PERIOD_FREEZES_COLLECTION = '_period_freezes'\n\n/** Sibling of {@link PERIODS_COLLECTION} holding archive companions (#613). */\nexport const PERIOD_ARCHIVES_COLLECTION = '_period_archives'\n\n/** Sibling of {@link PERIODS_COLLECTION} holding target-purge companions (#615). */\nexport const PERIOD_TARGET_PURGES_COLLECTION = '_period_target_purges'\n\n/**\n * Exclusive upper bound for a period's delete-marker purge window (#604).\n * Markers carry no business date (empty body), only write-time `_ts`, so freeze\n * purges markers with `_ts < bound`, `bound` being the instant just after the\n * period's inclusive `endDate`: a date-only `endDate` seals through end-of-day\n * → next midnight; a full-timestamp `endDate` seals through that instant → +1ms.\n */\nexport function periodExclusiveUpperBound(endDate: string): string {\n  const ms = Date.parse(endDate)\n  if (Number.isNaN(ms)) throw new ValidationError(`freezePeriod: unparseable period endDate \"${endDate}\".`)\n  const dateOnly = /^\\d{4}-\\d{2}-\\d{2}$/.test(endDate)\n  return new Date(ms + (dateOnly ? 86_400_000 : 1)).toISOString()\n}\n"],"mappings":";;;;;AAcO,IAAM,qBAAqB;AAG3B,IAAM,4BAA4B;AAGlC,IAAM,6BAA6B;AAGnC,IAAM,kCAAkC;AASxC,SAAS,0BAA0B,SAAyB;AACjE,QAAM,KAAK,KAAK,MAAM,OAAO;AAC7B,MAAI,OAAO,MAAM,EAAE,EAAG,OAAM,IAAI,gBAAgB,6CAA6C,OAAO,IAAI;AACxG,QAAM,WAAW,sBAAsB,KAAK,OAAO;AACnD,SAAO,IAAI,KAAK,MAAM,WAAW,QAAa,EAAE,EAAE,YAAY;AAChE;","names":[]}

package/dist/{chunk-3XKESW5E.js → chunk-SL3PLML2.js}

@@ -4,10 +4,10 @@ import {
   persistUserVisibility,
   readUserVisibility,
   saveUserEnvelope
-} from "./chunk-WZ3NCMK6.js";
+} from "./chunk-6PFST3FC.js";
 import {
   PolicyDeniedError
-} from "./chunk-QZWTRENR.js";
+} from "./chunk-AR5D76T2.js";
 
 // src/with-party/directory/user-envelope/api.ts
 var UserApi = class {
@@ -379,4 +379,4 @@ export {
   UserApi,
   createUserApi
 };
-//# sourceMappingURL=chunk-3XKESW5E.js.map
+//# sourceMappingURL=chunk-SL3PLML2.js.map

package/dist/{chunk-BYFXLDVV.js → chunk-TJOUKMWF.js}

@@ -1,6 +1,6 @@
 import {
   SCHEMAS_COLLECTION
-} from "./chunk-OBPVWOSQ.js";
+} from "./chunk-Q6MXHDSE.js";
 import {
   BLOB_CHUNKS_COLLECTION,
   BLOB_COLLECTION,
@@ -8,11 +8,11 @@ import {
   BLOB_INTENT_COLLECTION,
   BLOB_SLOTS_PREFIX,
   BLOB_VERSIONS_PREFIX
-} from "./chunk-NQSO4UAH.js";
+} from "./chunk-ELJOLQIG.js";
 import {
   assembleBundleContainer,
   buildExtractedPartitionWrapper
-} from "./chunk-SGQ4N5FS.js";
+} from "./chunk-KDWBVCIX.js";
 import {
   generateULID
 } from "./chunk-ZJADGNYF.js";
@@ -23,11 +23,11 @@ import {
   canonicalJson,
   envelopePayloadHash,
   hashEntry
-} from "./chunk-ISRKW4YN.js";
+} from "./chunk-V3EGXDFN.js";
 import {
   openEnvelopeJson,
   writeEnvelopeBody
-} from "./chunk-RZPOZPZU.js";
+} from "./chunk-623QEHDB.js";
 import {
   bufferToBase64,
   decrypt,
@@ -37,14 +37,14 @@ import {
   generateDEK,
   unwrapCek,
   wrapCek
-} from "./chunk-AKKRXT23.js";
+} from "./chunk-RPWMDIGK.js";
 import {
   NOYDB_BACKUP_VERSION,
   NOYDB_FORMAT_VERSION
-} from "./chunk-GZACYEOB.js";
+} from "./chunk-77AEMXFA.js";
 import {
   PartitionExtractionError
-} from "./chunk-QZWTRENR.js";
+} from "./chunk-AR5D76T2.js";
 
 // src/with-cargo/walk-closure.ts
 async function walkClosure(vault, opts) {
@@ -492,4 +492,4 @@ export {
   extractPartition,
   extractPartitionCore
 };
-//# sourceMappingURL=chunk-BYFXLDVV.js.map
+//# sourceMappingURL=chunk-TJOUKMWF.js.map

package/dist/{chunk-QD46HPZG.js → chunk-U2ID5A2I.js}

@@ -1,6 +1,6 @@
 import {
   SealedRecordNotEnabledError
-} from "./chunk-QZWTRENR.js";
+} from "./chunk-AR5D76T2.js";
 
 // src/with-audit/sealed-record/strategy.ts
 var NO_SEALED_RECORD = {
@@ -18,4 +18,4 @@ var NO_SEALED_RECORD = {
 export {
   NO_SEALED_RECORD
 };
-//# sourceMappingURL=chunk-QD46HPZG.js.map
+//# sourceMappingURL=chunk-U2ID5A2I.js.map

package/dist/{chunk-X4MVWPHV.js → chunk-UC5Y7OEJ.js}

@@ -4,13 +4,13 @@ import {
 import {
   base64ToBuffer,
   bufferToBase64
-} from "./chunk-AKKRXT23.js";
+} from "./chunk-RPWMDIGK.js";
 import {
   SessionExpiredError,
   SessionNotFoundError,
   SessionPolicyError,
   ValidationError
-} from "./chunk-QZWTRENR.js";
+} from "./chunk-AR5D76T2.js";
 
 // src/with-party/session/session.ts
 var subtle = globalThis.crypto.subtle;
@@ -364,4 +364,4 @@ export {
   clearDevUnlock,
   isDevUnlockActive
 };
-//# sourceMappingURL=chunk-X4MVWPHV.js.map
+//# sourceMappingURL=chunk-UC5Y7OEJ.js.map

package/dist/chunk-US2AR4BI.js

@@ -0,0 +1,25 @@
+import {
+  grant,
+  revoke,
+  rotateKeys
+} from "./chunk-FZAP4JNC.js";
+
+// src/with-party/team/active.ts
+function withTeam() {
+  return {
+    async grant(team, vault, options, factors) {
+      return team.runGrant(grant, vault, options, factors);
+    },
+    async revoke(team, vault, options, factors) {
+      return team.runRevoke(revoke, vault, options, factors);
+    },
+    async rotate(team, vault, collections) {
+      return team.runRotate(rotateKeys, vault, collections);
+    }
+  };
+}
+
+export {
+  withTeam
+};
+//# sourceMappingURL=chunk-US2AR4BI.js.map

package/dist/chunk-US2AR4BI.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/with-party/team/active.ts"],"sourcesContent":["/**\n * Enable the multi-user team capability (#267 Track A tail).\n *\n * Pass to `createNoydb({ teamStrategy: withTeam() })` to make `db.grant` /\n * `db.revoke` / `db.rotate` live. The keyring grant/revoke/rotate engines\n * are statically imported HERE — this module is reachable only through the\n * `@noy-db/hub/team` subpath (and the root barrel's tree-shakeable\n * re-export), so a single-user floor bundle never carries them. The facade\n * (`TeamFacade.runGrant` / `runRevoke` / `runRotate`) owns the policy-gate +\n * keyring plumbing and receives the engine as an argument.\n */\nimport type { TeamStrategy } from './strategy.js'\nimport { grant as grantEngine, revoke as revokeEngine, rotateKeys as rotateEngine } from './keyring.js'\n\nexport function withTeam(): TeamStrategy {\n  return {\n    async grant(team, vault, options, factors) {\n      return team.runGrant(grantEngine, vault, options, factors)\n    },\n    async revoke(team, vault, options, factors) {\n      return team.runRevoke(revokeEngine, vault, options, factors)\n    },\n    async rotate(team, vault, collections) {\n      return team.runRotate(rotateEngine, vault, collections)\n    },\n  }\n}\n"],"mappings":";;;;;;;AAcO,SAAS,WAAyB;AACvC,SAAO;AAAA,IACL,MAAM,MAAM,MAAM,OAAO,SAAS,SAAS;AACzC,aAAO,KAAK,SAAS,OAAa,OAAO,SAAS,OAAO;AAAA,IAC3D;AAAA,IACA,MAAM,OAAO,MAAM,OAAO,SAAS,SAAS;AAC1C,aAAO,KAAK,UAAU,QAAc,OAAO,SAAS,OAAO;AAAA,IAC7D;AAAA,IACA,MAAM,OAAO,MAAM,OAAO,aAAa;AACrC,aAAO,KAAK,UAAU,YAAc,OAAO,WAAW;AAAA,IACxD;AAAA,EACF;AACF;","names":[]}

package/dist/{chunk-ISRKW4YN.js → chunk-V3EGXDFN.js}

@@ -1,9 +1,9 @@
 import {
   envelopeBodyForHash
-} from "./chunk-RZPOZPZU.js";
+} from "./chunk-623QEHDB.js";
 import {
   sha256Hex
-} from "./chunk-AKKRXT23.js";
+} from "./chunk-RPWMDIGK.js";
 
 // src/with-commit/history/ledger/entry.ts
 function canonicalJson(value) {
@@ -67,4 +67,4 @@ export {
   parseIndex,
   envelopePayloadHash
 };
-//# sourceMappingURL=chunk-ISRKW4YN.js.map
+//# sourceMappingURL=chunk-V3EGXDFN.js.map

package/dist/{chunk-KFRPNHWR.js → chunk-V4O6YZSP.js}

@@ -1,14 +1,14 @@
 import {
   openEnvelopeJson
-} from "./chunk-RZPOZPZU.js";
+} from "./chunk-623QEHDB.js";
 import {
   encrypt,
   hmacSha256Hex,
   sha256Hex
-} from "./chunk-AKKRXT23.js";
+} from "./chunk-RPWMDIGK.js";
 import {
   NOYDB_FORMAT_VERSION
-} from "./chunk-GZACYEOB.js";
+} from "./chunk-77AEMXFA.js";
 
 // src/with-audit/forget/strategy.ts
 var NO_FORGET = { subjects: {} };
@@ -147,4 +147,4 @@ export {
   coerceSubjectId,
   readDottedPath
 };
-//# sourceMappingURL=chunk-KFRPNHWR.js.map
+//# sourceMappingURL=chunk-V4O6YZSP.js.map

package/dist/{chunk-3HUYRN24.js → chunk-W7C7MMIS.js}

@@ -1,9 +1,9 @@
 import {
   sha256Hex
-} from "./chunk-AKKRXT23.js";
+} from "./chunk-RPWMDIGK.js";
 import {
   MaterializedViewSourceUnknownError
-} from "./chunk-QZWTRENR.js";
+} from "./chunk-AR5D76T2.js";
 
 // src/with-formula/materialized-views/dependency-analyzer.ts
 function analyzeDependencies(query) {
@@ -366,4 +366,4 @@ export {
   MaterializedViewRegistry,
   wrapDbWithPredicates
 };
-//# sourceMappingURL=chunk-3HUYRN24.js.map
+//# sourceMappingURL=chunk-W7C7MMIS.js.map

package/dist/{chunk-BXHMZ2XW.js → chunk-WFYKIDCS.js}

@@ -1,36 +1,36 @@
 import {
   SyncScheduler
-} from "./chunk-MTJLOC3Y.js";
+} from "./chunk-55LKVALY.js";
 import {
   PERIODS_COLLECTION,
   PERIOD_ARCHIVES_COLLECTION,
   PERIOD_FREEZES_COLLECTION,
   PERIOD_TARGET_PURGES_COLLECTION,
   periodExclusiveUpperBound
-} from "./chunk-EZNTORXE.js";
+} from "./chunk-SBGXQK5I.js";
 import {
   envelopeBodySize
-} from "./chunk-RZPOZPZU.js";
+} from "./chunk-623QEHDB.js";
 import {
   isDeleteMarker,
   isTombstoneShape
-} from "./chunk-VH6SOCXH.js";
+} from "./chunk-EFJAAFBW.js";
 import {
   bufferToBase64,
   decrypt,
   derivePresenceKey,
   encrypt,
   generateIV
-} from "./chunk-AKKRXT23.js";
+} from "./chunk-RPWMDIGK.js";
 import {
   NOYDB_SYNC_VERSION
-} from "./chunk-GZACYEOB.js";
+} from "./chunk-77AEMXFA.js";
 import {
-  ConflictError,
-  ValidationError
-} from "./chunk-QZWTRENR.js";
+  ValidationError,
+  isConflictError
+} from "./chunk-AR5D76T2.js";
 
-// src/with-party/team/presence.ts
+// src/with-sync/presence.ts
 var PresenceHandle = class {
   adapter;
   syncAdapter;
@@ -237,7 +237,7 @@ var PresenceHandle = class {
   }
 };
 
-// src/with-party/team/sync-period-scope.ts
+// src/with-sync/period-scope.ts
 var PERIOD_SUMMARY_COLLECTIONS = [
   PERIODS_COLLECTION,
   PERIOD_FREEZES_COLLECTION,
@@ -282,7 +282,7 @@ function buildPeriodScope(option, records) {
   };
 }
 
-// src/with-party/team/sync.ts
+// src/with-sync/engine.ts
 var SyncEngine = class {
   local;
   remote;
@@ -367,12 +367,20 @@ var SyncEngine = class {
     this.role = opts.role ?? "sync-peer";
     this.label = opts.label;
     const policy = opts.syncPolicy;
-    if (policy && policy.push.mode !== "manual") {
+    if (policy && (policy.push.mode !== "manual" || policy.pull.mode !== "manual")) {
       this.scheduler = new SyncScheduler(policy, {
         push: () => this.push().then(() => {
         }),
-        pull: () => this.pull().then(() => {
-        }),
+        // #618 — role-gate the SCHEDULER-INITIATED pull. The Noydb layer gates
+        // pull-from-sink for explicit calls, but the scheduler calls the engine
+        // directly and would bypass it: a backup/archive-only primary with an
+        // `interval`/`on-focus` pull policy would pull ungated, reintroducing
+        // #616. This guards the engine self-initiating on a timer; an explicit
+        // `engine.pull()` still pulls for every role.
+        // `collections` is set by a 'phased' sequence — one collection per phase.
+        // A role-gated skip reports 'incomplete': nothing was pulled, so the
+        // phase must not mark its collection ready.
+        pull: (collections) => this.role === "sync-peer" ? this.pull(collections ? { collections: [...collections] } : void 0).then((r) => r.errors.length === 0 ? "complete" : "incomplete") : Promise.resolve("incomplete"),
         getDirtyCount: () => this.dirty.length
       });
     } else {
@@ -494,7 +502,7 @@ var SyncEngine = class {
             completed.push(i);
             pushed++;
           } catch (err) {
-            if (err instanceof ConflictError) {
+            if (isConflictError(err)) {
               const remoteEnvelope = await this.remote.get(this.vault, entry.collection, entry.id);
               if (remoteEnvelope) {
                 if (isTombstoneShape(remoteEnvelope)) {
@@ -520,7 +528,9 @@ var SyncEngine = class {
                   );
                   conflicts.push(conflict);
                   if (handled === "local") {
-                    await this.remote.put(this.vault, entry.collection, entry.id, conflict.local);
+                    const winner = this.advancePastRemote(conflict.local, remoteEnvelope);
+                    await this.remote.put(this.vault, entry.collection, entry.id, winner);
+                    if (winner !== conflict.local) await this.applyRemote(entry.collection, entry.id, winner);
                     completed.push(i);
                     pushed++;
                   } else if (handled === "remote") {
@@ -779,7 +789,7 @@ var SyncEngine = class {
             completed.push(i);
             pushed++;
           } catch (err) {
-            if (err instanceof ConflictError) {
+            if (isConflictError(err)) {
               const remoteEnvelope = await this.remote.get(this.vault, entry.collection, entry.id);
               if (remoteEnvelope) {
                 if (isTombstoneShape(remoteEnvelope)) {
@@ -805,7 +815,9 @@ var SyncEngine = class {
                   );
                   conflicts.push(conflict);
                   if (handled === "local") {
-                    await this.remote.put(this.vault, entry.collection, entry.id, conflict.local);
+                    const winner = this.advancePastRemote(conflict.local, remoteEnvelope);
+                    await this.remote.put(this.vault, entry.collection, entry.id, winner);
+                    if (winner !== conflict.local) await this.applyRemote(entry.collection, entry.id, winner);
                     completed.push(i);
                     pushed++;
                   } else if (handled === "remote") {
@@ -840,11 +852,13 @@ var SyncEngine = class {
   }
   /** Get current sync status. */
   status() {
+    const scheduled = this.scheduler?.status;
     return {
       dirty: this.dirty.length,
       lastPush: this.lastPush,
       lastPull: this.lastPull,
-      online: this.isOnline
+      online: this.isOnline,
+      ...scheduled && scheduled.readiness.size > 0 ? { readiness: scheduled.readiness, phase: scheduled.phase } : {}
     };
   }
   // ─── Auto-Sync ───────────────────────────────────────────────────
@@ -889,6 +903,21 @@ var SyncEngine = class {
    *  ordinary put. `isTombstoneShape` covers a forgotten-elsewhere record arriving as a shred;
    *  `isDeleteMarker` covers an ordinary (#589) delete — both route to the SAME 'delete' action
    *  (sync delete ≠ forget: freshness only, no shred/residue channel on the receiving side). */
+  /**
+   * #936 — a local-wins resolution write must SUPERSEDE the remote, never
+   * overwrite it in place: when the winner's `_v` does not already exceed
+   * the remote's (the same-`_v` push tie), re-stamp it at `remote._v + 1`.
+   * Without this the loser's next pull sees no delta (`_v`-based
+   * detection) and the peers stay silently diverged at the same version.
+   * `_v` is envelope metadata — AEAD-unbound, and `_vdig` is deliberately
+   * `_v`-independent — so the engine may restamp ciphertext. Callers must
+   * mirror the advanced envelope locally (`applyRemote`) so both sides
+   * agree. The 'merged' branch needs none of this: resolver output is
+   * already stamped `max(local, remote) + 1`.
+   */
+  advancePastRemote(winner, remote) {
+    return winner._v > remote._v ? winner : { ...winner, _v: remote._v + 1 };
+  }
   async applyRemote(collection, id, envelope) {
     await this.local.put(this.vault, collection, id, envelope);
     if (this.pullByteSink !== null) {
@@ -1010,7 +1039,7 @@ var SyncEngine = class {
   }
 };
 
-// src/with-party/team/sync-transaction.ts
+// src/with-sync/transaction.ts
 var SyncTransaction = class {
   comp;
   engine;
@@ -1073,4 +1102,4 @@ export {
   SyncEngine,
   SyncTransaction
 };
-//# sourceMappingURL=chunk-BXHMZ2XW.js.map
+//# sourceMappingURL=chunk-WFYKIDCS.js.map