@noy-db/hub 0.6.0-pre.4 → 0.6.0-pre.5

package/dist/team/index.js

@@ -2,7 +2,7 @@ import {
   MemoryDeviceSealProvider,
   beginEchoUnlock,
   withTeam
-} from "../chunk-IQRP74OO.js";
+} from "../chunk-CTHXKNMO.js";
 import {
   NO_TEAM,
   burnPaperRecoveryEntry,
@@ -31,7 +31,7 @@ import {
   unwrapMagicLinkGrant,
   updateAuthenticator,
   writeMagicLinkGrant
-} from "../chunk-O42AUQCP.js";
+} from "../chunk-CXJTWRBD.js";
 import "../chunk-3IXIU6FP.js";
 import {
   buildEchoBlock,
@@ -53,7 +53,7 @@ import {
   updateKeyringIdentity,
   verifyPrompt,
   verifyTypedEcho
-} from "../chunk-RW3XKAF3.js";
+} from "../chunk-WB24CH3C.js";
 import "../chunk-5JY5TSVY.js";
 import "../chunk-AHLJSVRL.js";
 import "../chunk-3URQC7EH.js";

package/dist/with-audit/guards/immutable-guard.d.ts

@@ -29,6 +29,20 @@ import type { GuardStrategy, GuardContext, GuardChange } from './types.js';
 export interface ImmutableGuardConfig<T extends Record<string, unknown>> {
     /** The collection to make WORM. */
     collection: string;
+    /**
+     * Optional stable per-vault identifier, forwarded verbatim to the
+     * underlying {@link GuardSpec.name} — `immutableGuard` is a wrapper
+     * around `withGuard` and grants the same identity affordance (#1006).
+     *
+     * Omit and `vault.listBehaviors()` falls back to a POSITIONAL
+     * `${collection}#${occurrence}` key, which renumbers when another
+     * guard on the same collection is registered ahead of this one. Pass
+     * a name whenever something joins to the behavior manifest by key —
+     * a generated rulebook, a diff between two vault versions, an audit
+     * report — so the identifier tracks the rule rather than its
+     * registration order.
+     */
+    readonly name?: string;
     /**
      * A record becomes immutable once this predicate holds. Evaluated on
      * the *existing* (already-persisted) record, so the write that first

package/dist/with-audit/periods/active.d.ts

@@ -2,10 +2,37 @@
  * Active periods strategy factory. Only reachable through the
  * `@noy-db/hub/periods` subpath.
  */
+import type { PeriodPartition } from './periods.js';
 import type { PeriodsStrategy } from './strategy.js';
+/** Options for {@link withPeriods}. */
+export interface WithPeriodsOptions {
+    /**
+     * Maps a collection to the timeline each of its records belongs to (#1005) —
+     * the answer to "which close calendar governs THIS record".
+     *
+     * ```ts
+     * withPeriods({
+     *   subjects: { receipts: (r) => [r.clientId, layerOf(r)] },
+     * })
+     * ```
+     *
+     * Same shape as `withForget({ subjects })`, which answers the same question
+     * for erasure. A collection with no entry — and every collection when
+     * `subjects` is omitted entirely — stays on the vault-wide timeline, so an
+     * existing vault behaves exactly as it did before partitions existed.
+     *
+     * Return `undefined` from a mapper to put an individual record back on the
+     * vault-wide timeline (e.g. a record that predates the field the mapping
+     * reads).
+     */
+    readonly subjects?: Readonly<Record<string, (record: Record<string, unknown>) => PeriodPartition | undefined>>;
+}
 /**
  * Build the default periods strategy. Pass into
  * `createNoydb({ periodsStrategy: withPeriods() })` to enable
  * `vault.closePeriod()` / `vault.openPeriod()` / write-guards.
+ *
+ * Pass `subjects` to run more than one close calendar in a single vault — see
+ * {@link WithPeriodsOptions.subjects}.
  */
-export declare function withPeriods(): PeriodsStrategy;
+export declare function withPeriods(options?: WithPeriodsOptions): PeriodsStrategy;

package/dist/with-audit/periods/index.d.ts

@@ -13,8 +13,10 @@
  * Vault can call them without TypeScript barrel gymnastics.
  */
 export { withPeriods } from './active.js';
+export type { WithPeriodsOptions } from './active.js';
 export type { PeriodsStrategy } from './strategy.js';
-export { PERIODS_COLLECTION, PERIOD_FREEZES_COLLECTION, PERIOD_ARCHIVES_COLLECTION, PERIOD_TARGET_PURGES_COLLECTION, periodExclusiveUpperBound, loadPeriods, chainAnchor, assertTsWritable, validatePeriodName, appendPeriodLedgerEntry, purgeMarkersOn, } from './periods.js';
-export type { PeriodRecord, PeriodFreezeRecord, PeriodArchiveRecord, PeriodTargetPurgeRecord, TargetPurgeCount, ClosePeriodOptions, OpenPeriodOptions, CarryForwardContext, ReadOnlyCollection, } from './periods.js';
+export type { PeriodScope } from './vault-facade.js';
+export { PERIODS_COLLECTION, PERIOD_FREEZES_COLLECTION, PERIOD_ARCHIVES_COLLECTION, PERIOD_TARGET_PURGES_COLLECTION, periodExclusiveUpperBound, resolvePeriodKey, samePartition, loadPeriods, chainAnchor, assertTsWritable, validatePeriodName, appendPeriodLedgerEntry, purgeMarkersOn, } from './periods.js';
+export type { PeriodPartition, PartitionResolver, PeriodRecord, PeriodFreezeRecord, PeriodArchiveRecord, PeriodTargetPurgeRecord, TargetPurgeCount, ClosePeriodOptions, OpenPeriodOptions, CarryForwardContext, ReadOnlyCollection, } from './periods.js';
 /** The un-opted-in stub for this service — exported so callers can compare against it (#844). */
 export { NO_PERIODS } from './strategy.js';

package/dist/with-audit/periods/periods.d.ts

@@ -189,6 +189,46 @@ export interface PeriodTargetPurgeRecord {
     readonly purgedBy: string;
     readonly targets: readonly TargetPurgeCount[];
 }
+/**
+ * Scope tuple for a period timeline (#1005).
+ *
+ * Identical in shape and semantics to `SequenceOptions.partition`: a
+ * partitioned timeline is always disjoint from any unpartitioned one, and from
+ * every other tuple. `['acme', 'vat']` and `['acme', 'wht']` are two
+ * independent close calendars for the same subject — which is the whole point,
+ * since sub-ledgers for one legal entity and one month routinely close on
+ * different statutory deadlines.
+ */
+export type PeriodPartition = readonly (string | number)[];
+/**
+ * Resolve the `_periods` storage key for a (name, partition) pair.
+ *
+ * Deliberately the same encoding as `resolveSequenceKey`: `name` verbatim when
+ * unpartitioned, else `${name}\x00${parts}` with each component
+ * `encodeURIComponent`d and `'/'`-joined. The null-byte separator cannot occur
+ * in a period name, so a partitioned key never collides with an unpartitioned
+ * one; URI-encoding keeps `['a/b']` distinct from `['a','b']`.
+ *
+ * @throws {ValidationError} on an empty component or a non-finite number.
+ * @internal
+ */
+export declare function resolvePeriodKey(name: string, partition?: PeriodPartition): string;
+/**
+ * Do two partitions denote the same timeline? Absent and empty both mean "the
+ * unpartitioned timeline", so they compare equal.
+ *
+ * @internal
+ */
+export declare function samePartition(a?: PeriodPartition, b?: PeriodPartition): boolean;
+/**
+ * Resolves a record to the timeline that governs it. Supplied by
+ * `withPeriods({ subjects })`; returns `undefined` for any collection with no
+ * mapping, which is what keeps an unconfigured vault on the single vault-wide
+ * timeline it has always had.
+ *
+ * @internal
+ */
+export type PartitionResolver = (collection: string, record: Record<string, unknown>) => PeriodPartition | undefined;
 /**
  * Stored record for one closed or opened accounting period. One entry
  * per period, keyed by `name` in the reserved `_periods` collection.
@@ -199,8 +239,19 @@ export interface PeriodTargetPurgeRecord {
  * into the next one, the same way the ledger's `prevHash` works.
  */
 export interface PeriodRecord {
-    /** Human-readable name (e.g., `'FY2026-Q1'`). Unique per vault. */
+    /**
+     * Human-readable name (e.g., `'FY2026-Q1'`). Unique per PARTITION — two
+     * timelines may each carry a `'2026-06'`, which is the normal case when one
+     * vault serves several subjects (#1005). Unique per vault when unpartitioned.
+     */
     readonly name: string;
+    /**
+     * The timeline this period belongs to. Absent = the vault-wide timeline.
+     * Two periods with the same `name` and different `partition` are unrelated:
+     * separate hash chains, separate close state, and the write guard applies
+     * each only to records that resolve to its own tuple.
+     */
+    readonly partition?: PeriodPartition;
     /**
      * Role discriminator. A period is `'closed'` from the moment its
      * `closedAt` is recorded; `'opened'` marks a period whose opening
@@ -283,11 +334,32 @@ export interface ClosePeriodOptions {
      * an explicit `dateField`.
      */
     readonly dateField?: string;
+    /**
+     * Close only this timeline (#1005). Omit for the vault-wide timeline.
+     *
+     * ```ts
+     * vault.closePeriod({
+     *   name: '2026-06', endDate: '2026-06-30', dateField: 'issuedAt',
+     *   partition: [clientId, 'vat'],
+     * })
+     * ```
+     *
+     * Which records the resulting seal applies to is decided by the
+     * `subjects` map passed to `withPeriods()` — without one, no record ever
+     * resolves to a partition and a partitioned close seals nothing.
+     */
+    readonly partition?: PeriodPartition;
 }
 /** Options for `vault.openPeriod()`. */
 export interface OpenPeriodOptions<TCollections = Record<string, Record<string, unknown>>> {
     /** Human-readable name for the new period. Must be unique. */
     readonly name: string;
+    /**
+     * The timeline to open in. Must match the partition of `fromPeriod` — a
+     * period cannot chain across timelines, since each carries its own hash
+     * chain (#1005).
+     */
+    readonly partition?: PeriodPartition;
     /** ISO lower bound of the new period (usually prior `endDate + 1 day`). */
     readonly startDate: string;
     /**
@@ -357,7 +429,7 @@ export declare function loadPeriods(adapter: NoydbStore, vault: string, decrypt:
  *
  * @internal
  */
-export declare function chainAnchor(records: readonly PeriodRecord[]): Promise<{
+export declare function chainAnchor(records: readonly PeriodRecord[], partition?: PeriodPartition): Promise<{
     priorPeriodName?: string;
     priorPeriodHash: string;
 }>;
@@ -382,7 +454,10 @@ export declare function chainAnchor(records: readonly PeriodRecord[]): Promise<{
 export declare function assertTsWritable(existing: {
     ts: string | null;
     record: Record<string, unknown> | null;
-} | null, incomingRecord: Record<string, unknown> | null, closedPeriods: readonly PeriodRecord[]): void;
+} | null, incomingRecord: Record<string, unknown> | null, closedPeriods: readonly PeriodRecord[], scope?: {
+    collection: string;
+    resolve?: PartitionResolver;
+}): void;
 /**
  * Sanity-check a proposed period name + endDate against existing
  * records. Shared by closePeriod / openPeriod so the two pathways
@@ -390,7 +465,7 @@ export declare function assertTsWritable(existing: {
  *
  * @internal
  */
-export declare function validatePeriodName(name: string, existing: readonly PeriodRecord[]): void;
+export declare function validatePeriodName(name: string, existing: readonly PeriodRecord[], partition?: PeriodPartition): void;
 /**
  * Wire a reserved-collection ledger append for a period record. The
  * period itself is stored via the adapter as an encrypted envelope;

package/dist/with-audit/periods/strategy.d.ts

@@ -12,21 +12,30 @@
  */
 import type { EncryptedEnvelope, NoydbStore } from '../../kernel/types.js';
 import type { LedgerStore } from '../../with-commit/history/ledger/store.js';
-import type { PeriodRecord } from './periods.js';
+import type { PeriodRecord, PeriodPartition, PartitionResolver } from './periods.js';
 /**
  * @internal
  */
 export interface PeriodsStrategy {
     loadPeriods(adapter: NoydbStore, vault: string, decrypt: (envelope: EncryptedEnvelope) => Promise<PeriodRecord>): Promise<PeriodRecord[]>;
-    chainAnchor(records: readonly PeriodRecord[]): Promise<{
+    chainAnchor(records: readonly PeriodRecord[], partition?: PeriodPartition): Promise<{
         priorPeriodName?: string;
         priorPeriodHash: string;
     }>;
     assertTsWritable(existing: {
         ts: string | null;
         record: Record<string, unknown> | null;
-    } | null, incoming: Record<string, unknown> | null, periods: readonly PeriodRecord[]): void;
-    validatePeriodName(name: string, existing: readonly PeriodRecord[]): void;
+    } | null, incoming: Record<string, unknown> | null, periods: readonly PeriodRecord[], scope?: {
+        collection: string;
+        resolve?: PartitionResolver;
+    }): void;
+    validatePeriodName(name: string, existing: readonly PeriodRecord[], partition?: PeriodPartition): void;
+    /**
+     * Record → timeline resolver built from `withPeriods({ subjects })` (#1005).
+     * `undefined` when the caller configured no subjects, which keeps every
+     * record on the vault-wide timeline.
+     */
+    readonly partitionOf?: PartitionResolver;
     appendPeriodLedgerEntry(ledger: LedgerStore | null, actor: string, envelope: EncryptedEnvelope, periodName: string, collection?: string): Promise<void>;
 }
 export declare const NO_PERIODS: PeriodsStrategy;

package/dist/with-audit/periods/vault-facade.d.ts

@@ -3,7 +3,16 @@ import type { NoydbStore } from '../../kernel/types.js';
 import type { LedgerStore } from '../../with-commit/history/ledger/store.js';
 import type { Collection } from '../../kernel/collection.js';
 import type { PeriodsStrategy } from './strategy.js';
-import { type PeriodRecord, type TargetPurgeCount, type ClosePeriodOptions, type OpenPeriodOptions } from './periods.js';
+import { type PeriodRecord, type TargetPurgeCount, type ClosePeriodOptions, type OpenPeriodOptions, type PeriodPartition } from './periods.js';
+/** Selects one period timeline. Omit — or pass an empty tuple — for the vault-wide one (#1005). */
+export interface PeriodScope {
+    readonly partition?: PeriodPartition;
+}
+/** The persisted side of a write, as the period write-guard sees it. */
+export interface PeriodGuardPrior {
+    readonly ts: string | null;
+    readonly record: Record<string, unknown> | null;
+}
 /** Everything the moving period methods touched on the vault's `this.*`. */
 export interface VaultPeriodsDeps {
     /** Resolved periods strategy (NO_PERIODS when not configured). */
@@ -56,7 +65,7 @@ export declare class VaultPeriods {
      * read only. Idempotent: a second call is a no-op that returns the
      * same merged record without re-purging or re-appending a ledger entry.
      */
-    freezePeriod(name: string): Promise<PeriodRecord>;
+    freezePeriod(name: string, options?: PeriodScope): Promise<PeriodRecord>;
     /**
      * Archive a closed period (#613): physically relocates its in-window
      * records (those with `_ts < periodExclusiveUpperBound(endDate)`) from the
@@ -66,7 +75,7 @@ export declare class VaultPeriods {
      * through to cold) and idempotent: a second call is a no-op returning the
      * same merged record.
      */
-    archivePeriod(name: string): Promise<PeriodRecord>;
+    archivePeriod(name: string, options?: PeriodScope): Promise<PeriodRecord>;
     /**
      * Target-purge a closed period (#615): sweeps delete markers off the vault's
      * PUSH-ONLY sync targets (`backup`/`archive`) via `purgeTargets`, recording a
@@ -76,22 +85,39 @@ export declare class VaultPeriods {
      * Idempotent once run; with no push-only targets it writes no companion and
      * is re-runnable.
      */
-    purgePeriodTargets(name: string): Promise<PeriodRecord>;
+    purgePeriodTargets(name: string, options?: PeriodScope): Promise<PeriodRecord>;
     /** Merge target-purge companion fields into a fresh `PeriodRecord` copy — never mutates `periodCache`. */
     private mergeTargetPurge;
     /** Merge archive companion fields into a fresh `PeriodRecord` copy — never mutates `periodCache`. */
     private mergeArchive;
     /** Merge freeze companion fields into a fresh `PeriodRecord` copy — never mutates `periodCache`. */
     private mergeFreeze;
-    /** Return every closed / opened period in `closedAt` order, merged with any freeze + archive companions. */
-    listPeriods(): Promise<readonly PeriodRecord[]>;
-    /** Look up a single period by name, merged with its freeze + archive + target-purge companions if any. Returns `null` if not found. */
-    getPeriod(name: string): Promise<PeriodRecord | null>;
-    /** Called by the gate bus before put/delete. */
+    /**
+     * Return every closed / opened period in `closedAt` order, merged with any
+     * freeze + archive companions.
+     *
+     * With no argument this spans EVERY timeline — the pre-#1005 behaviour, and
+     * the right default for an audit sweep. Pass `{ partition }` to scope to one
+     * timeline; `{ partition: [] }` (or omitting it) means the vault-wide one.
+     */
+    listPeriods(options?: PeriodScope): Promise<readonly PeriodRecord[]>;
+    /**
+     * Look up a single period by name within one timeline, merged with its
+     * freeze + archive + target-purge companions if any. Returns `null` if not
+     * found.
+     *
+     * Names are only unique per partition (#1005), so this resolves against the
+     * VAULT-WIDE timeline unless `{ partition }` says otherwise — matching how
+     * every pre-partition period is stored.
+     */
+    getPeriod(name: string, options?: PeriodScope): Promise<PeriodRecord | null>;
+    /** Resolve one period within the timeline named by `options` (vault-wide when absent). */
+    private findPeriod;
+    /** Called by the gate bus before put/delete. `collection` selects the subject mapping (#1005). */
     assertTsWritable(existing: {
         ts: string | null;
         record: Record<string, unknown> | null;
-    } | null, incoming: Record<string, unknown> | null): Promise<void>;
+    } | null, incoming: Record<string, unknown> | null, collection?: string): Promise<void>;
     private loadPeriodsCache;
     /** Generic reserved-collection writer — serves `_periods` and `_period_freezes` alike. */
     private writeReserved;

package/dist/with-party/team/keyring.d.ts

@@ -368,7 +368,6 @@ export declare function listUsersWithEnvelopes<T = unknown>(store: NoydbStore, v
     user: UserInfo;
     envelope: UserEnvelope<T> | null;
 }>>;
-/** Ensure a DEK exists for a collection. Generates one if new. */
 export declare function ensureCollectionDEK(store: NoydbStore, vault: string, keyring: UnlockedKeyring): Promise<(collectionName: string) => Promise<EnclaveKey>>;
 /** Check if a user has write permission for a collection. */
 export declare function hasWritePermission(keyring: UnlockedKeyring, collectionName: string): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noy-db/hub",
-  "version": "0.6.0-pre.4",
+  "version": "0.6.0-pre.5",
   "description": "Zero-knowledge, offline-first, encrypted document store — core library with AES-256-GCM, PBKDF2, multi-user keyring, and sync engine",
   "license": "MIT",
   "author": "vLannaAi <vicio@lanna.ai>",
@@ -210,14 +210,14 @@
     "node": ">=22.0.0"
   },
   "dependencies": {
-    "@noy-db/attestation": "0.6.0-pre.4"
+    "@noy-db/attestation": "0.6.0-pre.5"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
     "esbuild": "^0.25.0",
     "zod": "^4.0.0",
     "zod-to-json-schema": "^3.25.2",
-    "@noy-db/on-shamir": "0.6.0-pre.4"
+    "@noy-db/on-shamir": "0.6.0-pre.5"
   },
   "peerDependencies": {
     "zod-to-json-schema": "^3.25.0"