@noy-db/hub 0.6.0-pre.0 → 0.6.0-pre.10

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

@@ -146,7 +146,7 @@
  */
 import type { NoydbStore, EncryptedEnvelope } from '../../kernel/types.js';
 import type { LedgerStore } from '../../with-commit/history/ledger/index.js';
-export { PERIODS_COLLECTION, PERIOD_FREEZES_COLLECTION, PERIOD_ARCHIVES_COLLECTION, PERIOD_TARGET_PURGES_COLLECTION, periodExclusiveUpperBound, } from './window.js';
+export { PERIODS_COLLECTION, PERIOD_FREEZES_COLLECTION, PERIOD_ARCHIVES_COLLECTION, PERIOD_TARGET_PURGES_COLLECTION, PERIOD_REOPENS_COLLECTION, periodExclusiveUpperBound, } from './window.js';
 /**
  * Companion record recording that a closed period was frozen (its delete
  * markers physically purged). Stored in {@link PERIOD_FREEZES_COLLECTION},
@@ -177,6 +177,73 @@ export interface TargetPurgeCount {
     readonly role: 'backup' | 'archive';
     readonly purgedCount: number;
 }
+/**
+ * One entry in a period's append-only reopen/reclose log (#1022).
+ *
+ * Real accounting close is a three-state lifecycle — open / closed / reopened
+ * — not a one-way door. A month gets closed, a missing invoice arrives or a
+ * filing is rejected, the month is reopened, corrected, and reclosed. The audit
+ * value is not the ability to write again; it is the chain being able to say
+ * *closed at T1, reopened at T2 by U, reclosed at T3*.
+ */
+export interface PeriodReopenEvent {
+    readonly op: 'reopen' | 'reclose';
+    /** ISO timestamp the event was recorded. */
+    readonly at: string;
+    /** userId of the keyring that performed it. */
+    readonly by: string;
+    /**
+     * `reopen` only — ISO instant after which the period re-seals on its own,
+     * with nobody acting. Absent means the window stays open until an explicit
+     * `reclosePeriod`.
+     */
+    readonly until?: string;
+    /** Free-text justification, carried verbatim into the audit trail. */
+    readonly reason?: string;
+}
+/**
+ * Companion holding a period's reopen/reclose history (#1022). Stored in
+ * {@link PERIOD_REOPENS_COLLECTION}, keyed by the period's storage key — kept
+ * OFF the hash-chained `_periods/<name>` record for the same reason freeze and
+ * archive are: reopening must never rewrite the close, or the chain that proves
+ * the close happened is the very thing the reopen destroys.
+ *
+ * `events` is APPEND-ONLY. Where the other companions are single-shot and
+ * idempotent, this one accumulates, because the cycle repeats.
+ */
+export interface PeriodReopenRecord {
+    readonly period: string;
+    readonly partition?: PeriodPartition;
+    readonly events: readonly PeriodReopenEvent[];
+}
+/**
+ * Collapse an append-only reopen log into the return-only fields merged onto a
+ * {@link PeriodRecord} on read.
+ *
+ * Expiry is deliberately NOT resolved here: `reopenedUntil` is carried through
+ * verbatim and compared against the clock at write-guard time, so a bounded
+ * window re-seals on its own without anything having to run.
+ *
+ * @internal
+ */
+export declare function resolveReopenState(events: readonly PeriodReopenEvent[]): {
+    reopenedAt?: string;
+    reopenedBy?: string;
+    reopenedUntil?: string;
+    reopenReason?: string;
+    reclosedAt?: string;
+    reopenCount: number;
+};
+/**
+ * Is this period writable right now on account of a reopen? (#1022)
+ *
+ * Three ways to be sealed again: never reopened, explicitly reclosed after the
+ * last reopen, or a bounded window that has elapsed. The clock is read by the
+ * caller and passed in, so the guard and any diagnostic agree on one instant.
+ *
+ * @internal
+ */
+export declare function isEffectivelyReopened(period: PeriodRecord, nowIso: string): boolean;
 /**
  * Companion record noting that a closed+frozen period's delete markers were
  * swept off the vault's push-only sync targets (#615). Stored in
@@ -189,6 +256,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 +306,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
@@ -261,6 +379,19 @@ export interface PeriodRecord {
     readonly targetsPurgedAt?: string;
     readonly targetsPurgedBy?: string;
     readonly targetsPurged?: readonly TargetPurgeCount[];
+    /** #1022 return-only — collapsed from the `_period_reopens/<key>` append-only
+     *  log on read; NEVER written into the stored `_periods/<name>` record, so a
+     *  reopen cannot disturb the inter-period hash chain. Absent = never reopened.
+     *  `reclosedAt` present (and >= `reopenedAt`) means the window was closed
+     *  again explicitly; `reopenedUntil` in the past means it lapsed on its own.
+     *  Use {@link isEffectivelyReopened} rather than reading these directly. */
+    readonly reopenedAt?: string;
+    readonly reopenedBy?: string;
+    readonly reopenedUntil?: string;
+    readonly reopenReason?: string;
+    readonly reclosedAt?: string;
+    /** How many times this period has been reopened, ever. */
+    readonly reopenCount?: number;
 }
 /** Options for `vault.closePeriod()`. */
 export interface ClosePeriodOptions {
@@ -283,11 +414,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 +509,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 +534,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 +545,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,31 @@ 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, type PeriodReopenEvent } 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;
+}
+/** A scoped operation that also records a free-text justification in the audit trail. */
+export interface PeriodScopeWithReason extends PeriodScope {
+    readonly reason?: string;
+}
+/** Options for `vault.reopenPeriod()` (#1022). */
+export interface ReopenPeriodOptions extends PeriodScopeWithReason {
+    /**
+     * ISO instant after which the period re-seals BY ITSELF, with nobody acting.
+     * Omit for a window that stays open until an explicit `reclosePeriod()`.
+     *
+     * Expiry is evaluated against the clock on every write check, so a lapsed
+     * window needs no sweep, no timer and no cache invalidation to take effect.
+     */
+    readonly until?: string;
+}
+/** 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 +80,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 +90,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 +100,77 @@ 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>;
+    /**
+     * The full append-only reopen/reclose log for one period (#1022) — the record
+     * an audit actually asks for, in order. `[]` when never reopened.
+     */
+    listPeriodReopens(name: string, options?: PeriodScope): Promise<readonly PeriodReopenEvent[]>;
+    /**
+     * Return a closed period to a writable state (#1022).
+     *
+     * Close is a three-state lifecycle in practice — open / closed / reopened —
+     * because a month gets closed and then a missing invoice arrives, or a filing
+     * is rejected and must be amended. That is routine, and it is supposed to
+     * leave a trail.
+     *
+     * The `_periods/<key>` record is NOT touched: the reopen is appended to a
+     * companion log, so the inter-period hash chain that proves the close
+     * happened survives the reopen intact. The chain reads *closed at T1,
+     * reopened at T2 by U, reclosed at T3*.
+     *
+     * A reopen withdraws the PERIOD's veto and nothing else. Record-level rules —
+     * an `immutableGuard` on a sent receipt, a frozen field — are separate gate
+     * handlers registered ahead of the period gate, so a reopened month cannot
+     * resurrect a document that is independently locked. Period state can only
+     * ever widen what the record-level rule already permits.
+     *
+     * Reopening an already-open window is allowed and appends another event: that
+     * is how a window gets extended, and the log keeps both.
+     */
+    reopenPeriod(name: string, options?: ReopenPeriodOptions): Promise<PeriodRecord>;
+    /**
+     * Seal a reopened period again (#1022), ending the window explicitly rather
+     * than waiting for an `until` to lapse. Appends to the same log, so the
+     * close → reopen → reclose sequence is recoverable in order.
+     */
+    reclosePeriod(name: string, options?: PeriodScopeWithReason): Promise<PeriodRecord>;
+    /** Append one entry to a period's reopen log, ledger it, and invalidate the guard's view. */
+    private appendReopenEvent;
+    /** Merge each period's reopen log onto it. One adapter listing, not one per period. */
+    private mergeReopenState;
+    /** 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-audit/periods/window.d.ts

@@ -6,6 +6,16 @@ export declare const PERIOD_FREEZES_COLLECTION = "_period_freezes";
 export declare const PERIOD_ARCHIVES_COLLECTION = "_period_archives";
 /** Sibling of {@link PERIODS_COLLECTION} holding target-purge companions (#615). */
 export declare const PERIOD_TARGET_PURGES_COLLECTION = "_period_target_purges";
+/**
+ * Sibling of {@link PERIODS_COLLECTION} holding reopen/reclose companions (#1022).
+ *
+ * Unlike the freeze / archive / target-purge companions — each a single,
+ * idempotent, once-only record — this one holds an APPEND-ONLY EVENT LIST,
+ * because reopening is a repeating cycle: a month can be closed, reopened,
+ * reclosed, and reopened again. The audit value is the sequence, not the
+ * latest state.
+ */
+export declare const PERIOD_REOPENS_COLLECTION = "_period_reopens";
 /**
  * Exclusive upper bound for a period's delete-marker purge window (#604).
  * Markers carry no business date (empty body), only write-time `_ts`, so freeze

package/dist/with-cargo/index.d.ts

@@ -8,7 +8,7 @@
  * distributed query, addressing, and change-observation. It consolidates the
  * runtime floor formerly published as `/kernel` plus the orchestration delta.
  *
- * See docs/superpowers/specs/2026-07-01-noydb-architecture-lexicon.md.
+ * See docs/foundations/architecture-lexicon.md.
  *
  * @packageDocumentation
  */
@@ -37,7 +37,7 @@ export type { ExtractPartitionResult } from './extract-partition.js';
 export { adoptPartition, unsealDeks, createOwnerOnAdoptedPartition } from './adopt-partition.js';
 export type { AdoptPartitionOptions, AdoptPartitionResult, CreateOwnerResult, CreateOwnerOptions, CreateOwnerStandardOptions, CreateOwnerManagedOptions, } from './adopt-partition.js';
 export { TransferSealError, AdoptionStateError, PartitionExtractionError } from '../kernel/errors.js';
-export type { WriteHook } from '../port/with/write-hooks.js';
+export type { WriteHook, WriteEvent } from '../port/with/write-hooks.js';
 export type { WriteQueue } from '../kernel/write-queue.js';
 export type { WriteConflict } from '../kernel/types.js';
 export type { AccessibleVault } from '../kernel/types.js';

package/dist/with-commit/history/ledger/entry.d.ts

@@ -128,7 +128,7 @@ export interface LedgerEntry {
      * the role of the actor, the (collection, id, vBefore, vAfter) tuple
      * for every record touched, and which guard invariants passed.
      *
-     * See docs/superpowers/specs/2026-05-18-guards-design.md.
+     * See design-history/2026-05-18-guards-design.md.
      */
     readonly amendment?: {
         readonly reason: string;

package/dist/with-commit/numbering/descriptor.d.ts

@@ -1,7 +1,7 @@
 /**
  * @category capability
  * Deferred-numbering config descriptor. See
- * docs/superpowers/specs/2026-06-08-sealed-numbering-and-store-clock-design.md.
+ * design-history/2026-06-08-sealed-numbering-and-store-clock-design.md.
  */
 /** A registered deferred-numbering series. */
 export interface DeferredNumberingConfig {

package/dist/with-formula/derivations/with-derivation.d.ts

@@ -5,6 +5,6 @@ import type { DerivationSpec, DerivationStrategy } from './types.js';
  * plaintext after DEK unwrap. Outputs are encrypted with the same DEK
  * as the source and written via the standard `Collection.put` path.
  *
- * See docs/superpowers/specs/2026-05-01-dim14-derivation-v1-design.md.
+ * See design-history/2026-05-01-dim14-derivation-v1-design.md.
  */
 export declare function withDerivation<TSource extends Record<string, unknown>, TOutputs extends Record<string, Record<string, unknown> | ReadonlyArray<Record<string, unknown>>>>(spec: DerivationSpec<TSource, TOutputs>): DerivationStrategy;

package/dist/with-formula/materialized-views/types.d.ts

@@ -4,6 +4,7 @@ import type { ReduceSpec, Reduction } from '../../with-lookup/reduce/reduction.j
 import type { GroupedReduction } from '../../with-lookup/reduce/groupby.js';
 import type { JoinStrategy } from '../../kernel/query/join.js';
 import type { MoneyDescriptor } from '../../via/money/descriptor.js';
+import type { ExactMath } from '../../via/money/exact.js';
 import type { I18nTextDescriptor } from '../../via/i18n/core.js';
 /**
  * Minimal vault-shaped accessor passed to the MV `query()` callback.
@@ -269,6 +270,57 @@ export interface MaterializedViewSpec<TRow extends Record<string, unknown>> {
      * UNION-mode only. Ignored if {@link query} is set.
      */
     aggregate?: ReduceSpec;
+    /**
+     * Post-aggregate projection over ONE finished row (#1007).
+     *
+     * `aggregate` accepts reducers only, so a row can carry every input a
+     * derived value needs and still not express it — `max(0, netTotal - paid)`
+     * is not a reduction. `derive` closes that gap: it receives the row the
+     * grouping/aggregation pipeline just produced and returns a patch merged
+     * onto it, immediately before materialisation.
+     *
+     * ```ts
+     * aggregate: { paid: sum('paid'), netTotal: sum('netTotal') },
+     * derive: (row) => ({ toPay: Math.max(0, row.netTotal - row.paid) }),
+     * ```
+     *
+     * Deliberately narrow, and the narrowness is what keeps it safe under
+     * incremental recompute: **pure, single-row, no cross-row access, no second
+     * aggregation pass.** It only ever sees the row the reducer just produced,
+     * so a refresh triggered by one source write recomputes it correctly without
+     * the engine needing to know anything about the function.
+     *
+     * Returning `null` / `undefined` leaves the row unchanged. Returned keys
+     * that collide with a {@link groupBy} field throw
+     * `MaterializedViewConfigError` — a group key is the row's identity and
+     * feeds {@link rowKey}, so rewriting it would silently re-home the row.
+     *
+     * **Money:** money leaves a reducer as an exact decimal string, and
+     * `Number(a) - Number(b)` would put it straight back through binary floating
+     * point — `10.05 - 0.10` becomes `9.950000000000001`, which the money
+     * quantiser then refuses rather than storing drift. So `derive` receives
+     * {@link ExactMath} as its second argument; it works in scaled BigInt and
+     * cannot introduce a representation error:
+     *
+     * ```ts
+     * moneyFields: { netTotal: THB, paid: THB, toPay: THB },
+     * derive: (row, exact) => ({ toPay: exact.max(0, exact.sub(row.netTotal, row.paid)) }),
+     * ```
+     *
+     * Declare the derived field in {@link moneyFields} and the result is
+     * quantised through that descriptor before storage, exact at its scale.
+     *
+     * Note the one place `TRow` under-describes what arrives: a field declared
+     * in {@link moneyFields} reaches `derive` DECODED — the decimal string a
+     * reader would see, not the scaled integer the reducer left behind — even
+     * where `TRow` types it as `number` (which is what the arms' `map` emits).
+     * `ExactMath` accepts both, which is why its operations are the right tool
+     * here and why no cast is needed.
+     *
+     * Applies to every MV form (union, projection, and query), always as the
+     * last step before rows are materialised.
+     */
+    derive?: (row: TRow, exact: ExactMath) => Record<string, unknown> | null | undefined;
     /**
      * Money descriptors for the UNION-mode aggregate, keyed by the
      * OUTPUT/intermediate field name as it appears in the mapped row and

package/dist/with-formula/materialized-views/with-materialized-view.d.ts

@@ -21,8 +21,8 @@ import type { MaterializedViewSpec, MaterializedViewStrategy } from './types.js'
  * The three modes are mutually exclusive — exactly one of `query` /
  * `unionSources` / `projection` must be set at registration time.
  *
- * See docs/superpowers/specs/2026-05-20-dim14-mv-v2-design.md (single-source v2),
- * docs/superpowers/specs/2026-05-21-dim14-mv-multikey-and-union.md (UNION),
- * and docs/superpowers/specs/2026-07-25-join-projection-mv-design.md (projection).
+ * See design-history/2026-05-20-dim14-mv-v2-design.md (single-source v2),
+ * design-history/2026-05-21-dim14-mv-multikey-and-union.md (UNION),
+ * and design-history/2026-07-25-join-projection-mv-design.md (projection).
  */
 export declare function withMaterializedView<TRow extends Record<string, unknown>>(spec: MaterializedViewSpec<TRow>): MaterializedViewStrategy;

package/dist/with-formula/overlay-views/with-overlayed-view.d.ts

@@ -4,6 +4,6 @@ import type { OverlayedViewSpec, OverlayedViewStrategy } from './types.js';
  * a user-writable overlay so consumers can express operator-editable
  * lifecycles as one declarative block.
  *
- * See docs/superpowers/specs/2026-05-20-dim14-mv-v2-design.md.
+ * See design-history/2026-05-20-dim14-mv-v2-design.md.
  */
 export declare function withOverlayedView(spec: OverlayedViewSpec): OverlayedViewStrategy;

package/dist/with-party/custody/index.d.ts

@@ -20,7 +20,7 @@
  * vault instance (and thus no custody namespace) yet — it stays the exported
  * `team/deed.ts` function.
  *
- * @see docs/superpowers/specs/2026-06-17-fr6-deed-custodian-liberate-design.md
+ * @see design-history/2026-06-17-fr6-deed-custodian-liberate-design.md
  * @module
  */
 import type { GrantOptions, RevokeOptions, FactorProofBundle } from '../../kernel/types.js';

package/dist/with-party/directory/user-envelope/index.d.ts

@@ -5,7 +5,7 @@
  * `UserEnvelopeOversizedError` live in the kernel spine
  * (`kernel/types.ts` / `kernel/constants.ts` / `kernel/errors.ts`).
  *
- * @see docs/superpowers/specs/2026-05-05-user-envelope-design.md
+ * @see design-history/2026-05-05-user-envelope-design.md
  *
  * @module
  */

package/dist/with-party/directory/user-envelope/storage.d.ts

@@ -12,7 +12,7 @@
  * (`vault.user.*`) sits on top of this; permission gates, own-only
  * write enforcement, and presence-channel propagation live there.
  *
- * @see docs/superpowers/specs/2026-05-05-user-envelope-design.md
+ * @see design-history/2026-05-05-user-envelope-design.md
  *
  * @module
  */

package/dist/with-party/team/echo-ceremony.d.ts

@@ -1,6 +1,6 @@
 /**
  * `beginEchoUnlock` — the interactive ceremony API (spec
- * docs/superpowers/specs/2026-08-02-echo-secret-design.md, #940, Task 6).
+ * design-history/2026-08-02-echo-secret-design.md, #940, Task 6).
  *
  * Split out of `echo-secret.ts` (which owns only the block builders +
  * verifiers) because this module orchestrates BOTH `echo-secret.ts`
@@ -33,7 +33,7 @@ export interface EchoCeremony {
      * TYPE it.
      *
      * Conforming-player contract (spec
-     * docs/superpowers/specs/2026-08-02-echo-secret-design.md, "Ceremony"):
+     * design-history/2026-08-02-echo-secret-design.md, "Ceremony"):
      * when the owner does NOT recognize the revealed echo, the player MUST show
      * a hard phishing warning — do not continue, open the official app, rotate
      * the secret immediately — MUST NOT offer any skip or
@@ -57,7 +57,7 @@ export interface EchoCeremony {
  * cannot be resolved — sealed reveal under a foreign device).
  *
  * Conforming-player contract (spec
- * docs/superpowers/specs/2026-08-02-echo-secret-design.md): an owner who does
+ * design-history/2026-08-02-echo-secret-design.md): an owner who does
  * not recognize `ceremony.reveal` is looking at a phish. The player MUST then
  * show a hard warning (stop, open the official app, rotate the secret now),
  * MUST NOT offer a skip / "verification unavailable" fallback or any

package/dist/with-party/team/echo-secret.d.ts

@@ -1,6 +1,6 @@
 /**
  * Echo-block builders + verifiers (spec
- * docs/superpowers/specs/2026-08-02-echo-secret-design.md, #940).
+ * design-history/2026-08-02-echo-secret-design.md, #940).
  *
  * Builds and verifies the on-keyring {@link KeyringEchoBlock} declaration
  * for the 3-part echo ceremony (prompt → echo → key). This module owns:
@@ -24,7 +24,7 @@
  * offline brute-force oracles for anyone holding the keyring file (600K
  * PBKDF2 per guess), and the `sealed` reveal blob is unpadded so its length
  * discloses the echo's UTF-8 byte length — see the threat model in
- * `docs/superpowers/specs/2026-08-02-echo-secret-design.md`.
+ * `design-history/2026-08-02-echo-secret-design.md`.
  *
  * @module
  */

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

@@ -368,8 +368,17 @@ 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>>;
+/**
+ * The `Permissions` catch-all key (#1010). `Permissions` has always documented
+ * `'*'` as "the wildcard collection matching all collections in the vault", but
+ * nothing expanded it — a grantee handed the documented catch-all got no keys
+ * at all. It is honoured in three places, and they must agree: the DEK wrapping
+ * in `grant()`, and both permission checks below.
+ */
+export declare const PERMISSION_WILDCARD = "*";
+/** Does this permission map hand over the whole vault? */
+export declare function permissionsAreWildcard(permissions: Permissions | undefined): boolean;
 /** Check if a user has write permission for a collection. */
 export declare function hasWritePermission(keyring: UnlockedKeyring, collectionName: string): boolean;
 /** Check if a user has any access to a collection. */