@solidjs/signals 2.0.0-rc.2 → 2.0.0-rc.20

package/dist/types/store/projection.d.ts

@@ -1,70 +1,19 @@
-import { type Computed, type Refreshable } from "../core/index.js";
-import { type NoFn, type ProjectionOptions, type Store } from "./store.js";
-export declare function createProjectionInternal<T extends object = {}>(fn: (draft: T) => void | T | Promise<void | T> | AsyncIterable<void | T>, seed: Partial<T>, options?: ProjectionOptions): {
-    store: Refreshable<Store<T>>;
-    node: Computed<void | T>;
-};
+import type { Computed } from "../core/types.js";
+import type { Refreshable } from "../core/index.js";
+import { type NoArray, type NoFn, type ProjectionOptions, type Store } from "./types.js";
+/** The derive's pass: run `fn` against a draft of the store; commit its
+ * result (sync, or each async landing) through the reconcile channel.
+ * Draft validity is per run (R37): live from here until the NEXT run starts
+ * — a sync derive that subscribes to an external source and pushes into
+ * the draft from the callback (#3585) is the model use. */
+export declare function runProjectionComputed<T extends object>(wrappedStore: Store<T>, fn: (draft: T) => void | T | Promise<void | T> | AsyncIterable<void | T>, key: string | ((item: NonNullable<any>) => any) | null, wrapCommit?: (write: () => void, value: T) => void, aroundDraftWrite?: (op: () => void) => void): Computed<void | T>;
 /**
- * Creates a derived (projected) store. Like `createMemo` but for stores: the
- * derive function receives a mutable draft and either mutates it in place
- * (canonical) or returns a new value. Either way the result is reconciled
- * against the previous draft by `options.key` (default `"id"`), so surviving
- * items keep their proxy identity — only added/removed items are
- * created/disposed.
- *
- * If the derive returns a different entity than the one currently held (the
- * `/users/1` → `/users/2` shape), the store swaps to it rather than merging,
- * and nothing below it is treated as surviving.
- *
- * Returns the projected store directly (no setter — reads only).
- *
- * Use this when you want the structural-sharing / per-property tracking
- * behaviour of a store on top of a derived computation. For simple read-only
- * derivations, `createMemo` is lighter.
- *
- * @param fn receives the current draft; mutate it in place or return new
- *   data. Return is convenient for filter/derive shapes where mutation is
- *   awkward.
- * @param seed the backing store value to wrap and reconcile into
- * @param options `ProjectionOptions` — `name`, `key`. `key` defaults to
- *   `"id"`; specify it only when your data uses a different identity field
- *   (e.g. `{ key: "uuid" }` or `{ key: u => u.slug }`), or `null` to merge
- *   positionally with no keyed pass.
- *
- * @example
- * ```ts
- * // Mutation form — update individual fields on the draft.
- * const summary = createProjection<{ total: number; active: number }>(
- *   draft => {
- *     draft.total = users().length;
- *     draft.active = users().filter(u => u.active).length;
- *   },
- *   { total: 0, active: 0 }
- * );
- *
- * // Return form — produce a derived collection. Reconciled by `id` so each
- * // surviving user keeps the same store identity across recomputes.
- * const activeUsers = createProjection<User[]>(
- *   () => allUsers().filter(u => u.active),
- *   []
- * );
- * ```
- *
- * @see {@link https://github.com/solidjs/x-reactivity#createprojection}
+ * A derived store: `fn` runs in a computed and writes its draft; readers of
+ * the store's keys re-run only when the keys they read change (the
+ * firewall). `fn` may be async or an async iterator; the seed is a draft,
+ * never an observable value, until the first landing (A25).
  */
-export declare function createProjection<T extends object = {}>(fn: (draft: T) => void | T | Promise<void | T> | AsyncIterable<void | T>, seed: Partial<T> | Store<NoFn<T>>, options?: ProjectionOptions): Refreshable<Store<T>>;
-/**
- * Shared projection computed body used by both `createProjection` and the derived
- * form of `createOptimisticStore`. Encapsulates the write-trap draft, `storeSetter`
- * wrapping, the `handleAsync` subscription with a setter callback, and the commit
- * path (which must always go through `storeSetter` so the `writeOnly` guard is
- * engaged during `reconcile`'s property reads).
- *
- * `wrapCommit` is invoked for every commit (sync return and each async yield) and
- * lets callers layer extra context around the write — e.g. the optimistic store
- * re-enters `setProjectionWriteActive` so reconciles target `STORE_OVERRIDE`
- * instead of `STORE_OPTIMISTIC_OVERRIDE` even when an async yield fires outside
- * the outer `setProjectionWriteActive` scope.
- */
-export declare function runProjectionComputed<T extends object>(wrappedStore: Store<T>, fn: (draft: T) => void | T | Promise<void | T> | AsyncIterable<void | T>, key: string | ((item: NonNullable<any>) => any) | null, wrapCommit?: (write: () => void) => void, onDraftWrite?: () => void): Computed<void | T>;
-export declare function createWriteTraps(isActive?: () => boolean, onDraftWrite?: () => void): ProxyHandler<any>;
+export declare function createProjection<T extends object = {}>(fn: (() => T | Promise<T> | AsyncIterable<T>) & NoArray<T>, seed?: null, options?: Omit<ProjectionOptions, "seedLoadingValue">): Refreshable<Store<T>>;
+export declare function createProjection<T extends object = {}>(fn: (draft: T) => void | T | Promise<void | T> | AsyncIterable<void | T>, seed: NoFn<T> | Store<NoFn<T>>, options?: ProjectionOptions): Refreshable<Store<T>>;
+/** `createStore(fn, seed, options)`: a projection with a user setter. */
+export declare function createStoreDerived<T extends object = {}>(fn: (draft: T) => void | T | Promise<void | T> | AsyncIterable<void | T>, seed: T | null | undefined, options?: ProjectionOptions): [Refreshable<Store<T>>, (f: (draft: T) => T | void) => void];

package/dist/types/store/reconcile.d.ts

@@ -1,46 +1,3 @@
-/**
- * Shared body of `reconcile()` and the projection commit. `replace` is the
- * only difference: a projection commit is a value swap, not a merge — its root
- * proxy is a cell handed out by `createProjection` that can never change
- * reference, so a derive returning a different entity is not the slot mistake
- * `reconcile()` throws on. Nothing below the root survives that swap, which is
- * the rule the keyed diff already applies at a nested slot on a key mismatch.
- *
- * @internal
- */
-export declare function reconcileState(value: any, state: any, key: any, replace: boolean): void;
-/**
- * Returns a draft-mutating function that smart-merges `value` into a store,
- * preserving fine-grained reactivity: only changed leaves trigger updates.
- *
- * With a `key` (default `"id"`), array items whose key matches between old
- * and new states keep their identity (updated in place, moves and removals
- * update the corresponding signals) — the shape for keyed server payloads.
- * Items without the key field fall back to positional matching.
- *
- * With `key: null`, matching is purely positional: index N of the new array
- * merges into index N of the old, and object properties merge recursively —
- * the classic pattern for fixed-shape data that churns in place (dashboards,
- * monitors), where no keyed diff pass is needed or wanted.
- *
- * Merging into a slot that holds a *different* entity throws — the caller
- * picked the slot, so a key mismatch there is a bug.
- *
- * @param value the next state to merge in
- * @param key property name (string) or extractor function for stable
- * identity (default `"id"`); pass `null` for positional merging
- *
- * @example
- * ```ts
- * const [todos, setTodos] = createStore<Todo[]>([]);
- *
- * async function refresh() {
- *   const fresh = await api.getTodos();
- *   setTodos(reconcile(fresh)); // diff-merge by `id`
- * }
- *
- * // fixed-shape polling data — positional merge
- * setStats(reconcile(nextStats, null));
- * ```
- */
-export declare function reconcile<T extends U, U>(value: T, key?: string | ((item: NonNullable<any>) => any) | null): (state: U) => void;
+type KeyFn = (item: any) => any;
+export declare function reconcileState(value: any, state: any, key: string | KeyFn | null | undefined, replace?: boolean): void;
+export {};

package/dist/types/store/store.d.ts

@@ -1,138 +1,135 @@
-import { type Signal } from "../core/index.js";
-import type { Refreshable } from "../core/index.js";
-/** A read-only view of a store's value as seen by consumers. Mutate it via the paired `StoreSetter`. */
-export type Store<T> = Readonly<T>;
-/**
- * A store setter. The callback receives a writable **draft** of the store.
- *
- * - **Mutate in place (canonical):** `s.foo = 1`, `s.list.push(x)`,
- *   `s.list.splice(i, 1)`. This is the default form for most updates.
- * - **Return a new value:** for shapes where mutation is awkward, most
- *   commonly removing items (`s => s.list.filter(...)`). Arrays are replaced
- *   by index (length adjusted); objects are shallow-diffed at the top level
- *   (keys present in the returned value are written, missing keys deleted).
- *
- * The setter does **not** perform keyed reconciliation. If you need surviving
- * items to keep their store identity across full-array replacement, use the
- * projection form — `createStore(fn, seed, { key })` or `createProjection` —
- * whose derive function reconciles its return by `options.key`.
- */
-export type StoreSetter<T> = (fn: (state: T) => T | void) => void;
-/** Tuple returned by the plain `createStore(initialValue)` form. */
-export type StoreReturn<T> = [get: Store<T>, set: StoreSetter<T>];
-/** Tuple returned by the derived `createStore(fn, seed, options?)` form. */
-export type ProjectionStoreReturn<T> = [get: Refreshable<Store<T>>, set: StoreSetter<T>];
-/** Base options for store primitives. */
-export interface StoreOptions {
-    /** Debug name (dev mode only) */
-    name?: string;
-}
-/** Options for derived/projected stores created with `createStore(fn)`, `createProjection`, or `createOptimisticStore(fn)`. */
-export interface ProjectionOptions extends StoreOptions {
-    /** Key property name or function for reconciliation identity; `null` merges positionally */
-    key?: string | ((item: NonNullable<any>) => any) | null;
-    /** Single-layer store: root keys reactive, values raw records replaced by reference */
-    shallow?: boolean;
-    /**
-     * Treat the seed as commit #0: the store is born committed with the seed's
-     * contents, shown until the derive's first real answer lands. While that
-     * first answer is in flight, reads serve the seed everywhere — nothing
-     * suspends to a `<Loading>` boundary, no transition is held, and
-     * `isPending` stays false (the seed answers by declaration; first-load
-     * affordances belong to the data, e.g. a `skeleton: true` field in the
-     * seed). Once the first answer lands (reconciled into the seed), refetches
-     * use normal pending semantics with `isPending` true.
-     *
-     * The store equivalent of `MemoOptions.loadingValue`; the seed already
-     * carries the placeholder shape, so this is just the opt-in.
-     */
-    seedLoadingValue?: boolean;
+import type { Signal } from "../core/types.js";
+import { type StoreFamily, type StoreTarget } from "./target.js";
+import { type StoreOptions } from "./types.js";
+export { $PROXY, $TARGET, $TRACK, markRaw } from "./types.js";
+export type SetStoreFunction<T> = (fn: (draft: T) => T | void) => void;
+export declare function wrap<T extends Record<PropertyKey, any>>(value: T, parent?: StoreTarget | null, parentKey?: PropertyKey | null, fam?: StoreFamily | null): T;
+/** Unwrap our own proxies to their current backing; leave everything else.
+ * A projection draft wrapper is registered as its target's alias
+ * (projection.ts `wrapDraft`) — adopted as a backing, it would forward to
+ * itself (#3767). */
+export declare function unwrapValue(v: any): any;
+export declare function sameKey(a: any, b: any): boolean;
+/** The container node's arrangement guess: the rows (or keys) the setter
+ * left the container with, in order. Its comparator judges a landing or a
+ * revert against it by row identity — by key when the family has one
+ * (the server's object for a guessed row is the same row). */
+export declare class LaneView {
+    rows: Record<PropertyKey, any>;
+    /** The backing the guess is shown over: the committed one at the
+     * guess, the composed arrangement after a re-base (optimistic.ts). */
+    base: Record<PropertyKey, any>;
+    /** Keys the setter REMOVED from the view it saw (a deliberate delete,
+     * not a row the truth has yet to show): a re-base does not restore
+     * them. `null` when none. */
+    removed: Set<unknown> | null;
+    constructor(rows: Record<PropertyKey, any>, 
+    /** The backing the guess is shown over: the committed one at the
+     * guess, the composed arrangement after a re-base (optimistic.ts). */
+    base: Record<PropertyKey, any>, 
+    /** Keys the setter REMOVED from the view it saw (a deliberate delete,
+     * not a row the truth has yet to show): a re-base does not restore
+     * them. `null` when none. */
+    removed?: Set<unknown> | null);
 }
-export type NoFn<T> = T extends Function ? never : T;
-type DataNode = Signal<any>;
-type DataNodes = Record<PropertyKey, DataNode>;
-/**
- * Brand symbols used internally by the store proxy / projection plumbing.
- * Cross-package wiring; not part of the user-facing API.
- *
- * @internal
- */
-export declare const $TRACK: unique symbol, $TARGET: unique symbol, $PROXY: unique symbol, $DELETED: unique symbol, $AFFECTS: unique symbol;
-export declare const STORE_VALUE = "v", STORE_NODE = "n", STORE_HAS = "h", STORE_PARENT = "u", STORE_DESC = "d", STORE_SHALLOW = "s";
-/** Structural view of a store target as shared machinery sees it (the real
- * shape is `StoreNextTarget` in ./next/target.ts). */
-export type StoreNode = {
-    [$PROXY]: any;
-    [STORE_VALUE]: Record<PropertyKey, any>;
-    [STORE_NODE]?: DataNodes;
-    [STORE_HAS]?: DataNodes;
-    [STORE_PARENT]?: StoreNode;
-    [STORE_SHALLOW]?: boolean;
-    [STORE_DESC]?: boolean;
-};
-export declare namespace SolidStore {
-    interface Unwrappable {
-    }
-}
-export type NotWrappable = string | number | bigint | symbol | boolean | Function | null | undefined | SolidStore.Unwrappable[keyof SolidStore.Unwrappable];
-/**
- * Marks a value as raw: no store will ever wrap it — every store presents it
- * as-is, tracked by reference at whatever slot holds it and updated by
- * replacement. Useful for class instances and external objects (editors,
- * scene graphs, Maps) and for record-shaped data updated wholesale. Sticky
- * for the value's lifetime.
- */
-export declare let rawValuesUsed: boolean;
-export declare function isRawValue(value: any): boolean;
-export declare function markRaw<T>(value: T): T;
-export declare function markRawOne(v: any): void;
-export declare function markRawIngest(container: any): void;
-export declare function isWrappable<T>(obj: T | NotWrappable): obj is T;
-export declare function setWriteOverride(value: boolean): void;
-export declare function getWriteOverride(): boolean;
-export declare function ownEnumerableKeys(o: object): (string | symbol)[];
-/**
- * Scope inheritance for late-created nodes: every live mark whose identity
- * scope contains the owning record's raw — and, for keyed marks, whose key
- * is this property — gets counted on the new node. Inherited marks live
- * exactly as long as the scope's carrier — the release hook below drops
- * them with the entry.
- */
-export declare function inheritAffectsMarks(node: DataNode, raw: object, property: PropertyKey): void;
-/** Next-store node factory for affects carriers/slots: injected by the
- * rewrite module (next targets alias the legacy field names, so everything
- * here EXCEPT node creation works on them structurally). */
-export declare let nextAffectsNodeResolver: ((target: any, key: PropertyKey) => DataNode) | null;
-export declare function setNextAffectsNodeResolver(fn: (target: any, key: PropertyKey) => DataNode): void;
-/** Next-store optimistic view for the declaration walk (optimistic rows
- * pushed before the declaration are in motion too — legacy reads its write
- * overlays; next composes armed-node overrides). */
-export declare let nextOptimisticViewResolver: ((target: any, raw: any) => any) | null;
-export declare function setNextOptimisticViewResolver(fn: (target: any, raw: any) => any): void;
-/** @internal birth inheritance for nodes created inside a live mark window —
- * exported for the rewrite's node factories. */
-export declare function affectsScopesLive(): boolean;
-/**
- * Witness live mark coverage of a record into the active isPending() probe.
- * Tracked reads don't need this — they go through real signal nodes, which
- * carry marks directly (declaration walk or birth inheritance). This covers
- * UNTRACKED probes reading through records whose nodes never materialized
- * (no observer ever subscribed, so no node exists to carry the mark).
- * Callers guard on `pendingCheckActive`, so plain reads never pay for this.
- *
- * @internal
- */
-export declare function witnessAffectsMark(target: StoreNode, property?: PropertyKey): void;
-/**
- * Resolves the store nodes an `affects()` declaration marks: with a `key`,
- * the named slot's leaf node (upserted so the mark has an addressable
- * carrier); without, the record's $AFFECTS carrier plus every LIVE node in
- * its subtree (the edges existing readers subscribed through), with the
- * subtree's identities snapshotted into the mark's scope so nodes created
- * during the window — and untracked probes over captured proxies — resolve
- * against it (#2882).
+/** A container node's value as a backing: the base an arrangement guess is
+ * shown over, else the value itself. */
+export declare function asBacking(v: any): Record<PropertyKey, any>;
+/** The container node's comparator: a staging is a backing (identity — a
+ * pending backing is never "equal" to the committed one); a lane value is
+ * an arrangement (`LaneView`), judged by the optimistic machinery. */
+export declare const containerEquals: (this: any, a: any, b: any) => boolean;
+export declare function getNode(target: StoreTarget, key: PropertyKey, accKnown?: -1 | 0 | 1): Signal<any>;
+export declare function getHasNode(target: StoreTarget, key: PropertyKey): Signal<boolean>;
+/** The container node (plan sec. 31.3): created by the first structural subscription
+ * or the first write that needs to stage. Its committed value is the
+ * committed backing. */
+export declare function getContainerNode(target: StoreTarget): Signal<any>;
+export declare function bumpDeep(t: StoreTarget): void;
+export declare function nameStore(proxy: any, name: string | undefined, loc?: string): void;
+/** Shallow clone into store ownership. Plain data (grade 2) spreads; anything
+ * else copies descriptors (accessors kept, everything made configurable). */
+export declare function cloneRaw(source: Record<PropertyKey, any>, t: StoreTarget): Record<PropertyKey, any>;
+/** Downgrade an overlay to a real clone (a consumer needs a container). */
+export declare function materializePB(target: StoreTarget): Record<PropertyKey, any>;
+/** Adoption (a setter's returned replacement; reconcile and projection
+ * landings in S3): the incoming object becomes the backing by reference at
+ * the fold — no clones, no user-object mutation, ownership resets to
+ * shared. It is the container's staging until then (signal parity: a
+ * handler reads the committed frame until the flush; a hold keeps it
+ * staged with the rest). The nodes are told now, diffed against the view
+ * they were LAST told (#3296): the draft's pending backing when one
+ * preceded the adoption this batch — its node writes were real, and the
+ * adoption's re-stage cancels or confirms each — else the committed
+ * backing. */
+export declare function adoptPB(target: StoreTarget, incoming: Record<PropertyKey, any>, notify?: boolean): void;
+export declare function runDirect(fn: () => void): void;
+/** Is the open setter a user's? (reconcile.ts: a user's reconcile on an
+ * optimistic family writes the draft.) */
+export declare function userWriting(): boolean;
+/** Two raws that wrap to the same target are the same logical value. */
+export declare function targetsEqual(ov: any, nv: any): boolean;
+/** Positional identity IS content for arrays (R15). */
+export declare function arrayStructureChanged(old: any[], neu: any[]): boolean;
+export declare function membershipChanged(old: Record<PropertyKey, any>, neu: Record<PropertyKey, any>): boolean;
+/** One leaf's notification for an adoption diff (descriptor-aware). */
+export declare function notifyKeyDiff(node: Signal<any>, key: PropertyKey, old: Record<PropertyKey, any>, neu: Record<PropertyKey, any>, probe?: boolean): void;
+export declare function hasAccessorFlag(node: Signal<any>): boolean;
+/** One leaf's notification when the caller already has both values. */
+export declare function notifyKeyValue(node: Signal<any>, key: PropertyKey, ov: any, nv: any, old: Record<PropertyKey, any>, neu: Record<PropertyKey, any>): void;
+/** The structural half of an adoption's notifications (reconcile does the
+ * leaves itself): presence by `in`, the container by membership. Presence
+ * is DIFFED `old` → `neu` like the leaves (#3743): a presence node is
+ * written only where `in` changed between the view it was last told
+ * (#3296) and the adoption — `setSignal` joins a held node's transaction
+ * before its equality gate (A34 (1)), so repeating an unchanged absence to
+ * a node an action holds would make the whole tick the action's (an
+ * unrelated `a.value` stayed stale until the action settled). A real
+ * change still writes, and on a held node still proposes. A live chained
+ * `old` (a store proxy, §7b) reflects the inner store, not what the node
+ * was last told — written unconditionally, as before; its container too
+ * (#4361).
  *
- * @internal
- */
-export declare function getStoreAffectsNodes(target: StoreNode, key?: PropertyKey): DataNode[];
-export {};
+ * The container is told of an arrangement change when it has structural
+ * subscribers OR carries an arrangement guess (S4): for a guessed
+ * container the write is the landing that judges the guess (Q-D, plan
+ * sec. 39 — confirm, supersede, or hold beneath), not a subscriber
+ * notification, and a landing whose truth changed no guessed key's value
+ * or presence (a newer question's rows beneath an optimistic push) still
+ * answers the arrangement — before, only the presence write reached the
+ * lane, by accident of being unconditional. */
+export declare function notifyFoldTail(t: StoreTarget, old: Record<PropertyKey, any>, neu: Record<PropertyKey, any>): void;
+/** An adoption's notifications: every node of the target, diffed `old` →
+ * `neu` (value nodes by key, presence by `in`, the container by
+ * membership, the deep witness by identity). */
+export declare function notifyFold(t: StoreTarget, old: Record<PropertyKey, any>, neu: Record<PropertyKey, any>): void;
+/** The committed backing: the container node's committed value while a
+ * batch is staged on it (an adoption swaps `t.v` eagerly — INTERNALS §3,
+ * "adoption is eager by contract" — and the node keeps the frame committed
+ * readers under a hold still see), `t.v` otherwise. */
+export declare function committed(t: StoreTarget): Record<PropertyKey, any>;
+/** The same row at a slot, as the adoption pairs rows (reconcile.ts): two
+ * objects whose keys agree — positionally for an unkeyed family. */
+export declare function sameRow(pv: any, nv: any, keyFn: ((item: any) => any) | null): boolean;
+/** A chained backing's child (§7b): a raw the inner family owns, or holds
+ * at this key, is served as the inner store's wrapper — never a fresh
+ * raw-keyed one — so the chained targets are the same objects across
+ * settled and pending views. */
+export declare function resolveChainedRaw(target: StoreTarget, key: PropertyKey, v: object): any;
+export declare function storeSetter<T>(proxy: T, fn: (draft: T) => T | void, guard?: boolean): void;
+export declare function createStore<T extends Record<PropertyKey, any>>(initialValue: T, options?: StoreOptions): [T, SetStoreFunction<T>];
+/** True when `proxy` is a SHALLOW store (children served verbatim, slots
+ * replaced by reference — #2932). The list driver uses this to choose the
+ * slot-patch channel (collected row bodies) over per-record registration. */
+export declare function storeIsShallow(proxy: any): boolean;
+/** True when `proxy` belongs to a projection family (S3). */
+export declare function storeHasFamily(proxy: any): boolean;
+/** True when `proxy` belongs to an OPTIMISTIC family (S4). */
+export declare function storeHasOptimisticFamily(proxy: any): boolean;
+/** Tracking snapshot: subscribes every reachable record's container and deep
+ * witness (one node per record, not one per path), then snapshots. */
+export declare function deep<T>(value: T): T;
+/** Non-tracking snapshot: source identity for unowned subtrees (zero copy),
+ * a copy for owned ones (they are by definition modified relative to the
+ * source). Sees the pending backing (R27). */
+export declare function snapshot<T>(value: T): T;

package/dist/types/store/storePath.d.ts

@@ -1,4 +1,4 @@
-import { type NotWrappable } from "./store.js";
+import { type NotWrappable } from "./types.js";
 type W<T> = Exclude<T, NotWrappable>;
 type KeyOf<T> = number extends keyof T ? 0 extends 1 & T ? keyof T : [T] extends [never] ? never : [T] extends [readonly unknown[]] ? number : keyof T : keyof T;
 export type CustomPartial<T> = T extends readonly unknown[] ? "0" extends keyof T ? {

package/dist/types/store/target.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Store — target & ownership (INTERNALS-STORE-STATE.md §1, §5b; plan sec. 31).
+ *
+ * The proxy wraps this internal target, never the raw. `v` is the single
+ * committed home; the pending backing (`pb`) is the CoW overlay/clone the
+ * draft mutates natively — and, on L2, the **container node's staging**
+ * (plan sec. 31.3, Q-A): `k` is the `$TRACK` node given a value. Its `_value` is the
+ * committed backing, its `_pendingValue` the pending backing, so the
+ * scheduler owns the backing's lifetime (park, commit, revert) and the store
+ * keeps no fold ledger of its own. The fold at the flush's commit
+ * (`_storeCommit`) is the one mutation of owned raw.
+ *
+ * Creation budget (§5b): one minimal target + one proxy + one lookup entry
+ * per read-through object; nodes, presence nodes, the container node and
+ * the deep witness are lazy — materialized by subscription, or (the
+ * container) by the first write that needs to stage.
+ */
+import type { Computed, Owner, Signal } from "../core/types.js";
+/** Projection family (§7b; returns in S3): children wrap into the family's
+ * own map (writes land in the projection, never the source family), and the
+ * family's node is the firewall every read through it pulls first. */
+export interface StoreFamily {
+    /** Optimistic family (S4): the setter's writes are guesses. */
+    opt?: boolean;
+    /** Targets carrying a lane value on one of their nodes (reads compose the
+     * view over the truth — optimistic.ts); dropped lazily once none is. */
+    overlaid?: Set<StoreTarget>;
+    /** The derive asked a new question over the family's guesses, stamped
+     * with that flush's clock (#4336, optimistic.ts `ask`): `clock + 1` from
+     * mainline over a live guess, `~clock` otherwise (a lane's work over no
+     * guess of its own, or no live guess left). */
+    asked?: number;
+    /** Normalized row-key fn (`options.key`, "id" default, null = unkeyed). */
+    key?: ((item: any) => any) | null;
+    map: WeakMap<object, StoreTarget>;
+    /** The projection computed — the firewall. Assigned after creation. */
+    node: Computed<any> | null;
+    /** Targets of the family that carry nodes: the derive's pending wakes
+     * their readers (A9) — the family's enumerable index, in place of a
+     * per-leaf chain; a target leaves it with its last node. */
+    live: Set<StoreTarget>;
+    /** A source's status reaching the derive by propagation (`familyStatus`). */
+    st?: (status: number) => void;
+    shallow?: boolean;
+    /** Derive run counter (proj R37): the run whose draft is live. */
+    run?: number;
+    /** The derive's pending reached the leaves' readers (`wakeFamily`) and no
+     * landing has settled them yet: the next commit walks the family
+     * (`settleFamily`). A sync commit with no wake behind it walks nothing. */
+    woke?: boolean;
+}
+/** One setter's written keys; `u` is the batch's earlier setters' (the
+ * fold's union), present only once a second setter writes the target. */
+export interface WrittenKeys extends Set<PropertyKey> {
+    u?: WrittenKeys;
+}
+export interface StoreTarget {
+    /** Committed backing: source object (shared) or owned clone. */
+    v: Record<PropertyKey, any>;
+    /** Pending backing for the current batch (null when settled) — the same
+     * object the container node stages (`k._pendingValue`). */
+    pb: Record<PropertyKey, any> | null;
+    /** cached: committed backing is another store's proxy (§7b chained). */
+    ch: boolean;
+    /** live value-node count (deleted-key sweep fast-out in the fused walk). */
+    nc: number;
+    /** Lazy per-property subscription nodes (slot nodes). */
+    n: Record<PropertyKey, Signal<any>> | null;
+    /** Lazy per-key presence nodes (`in` tracks presence, not value — R13). */
+    h: Record<PropertyKey, Signal<boolean>> | null;
+    /** Lazy CONTAINER node: membership/iteration/`$TRACK`/`length`
+     * subscriptions (§6) and the backing's staging home (plan sec. 31.3). */
+    k: Signal<any> | null;
+    /** Keys written through the traps by the current setter, with the earlier
+     * setters' of the batch chained behind (`u`) until the fold commit. Bounds
+     * the setter notify/hold-check to O(written) instead of O(subscribed
+     * nodes) — a record with thousands of per-key subscriptions (selection
+     * maps) would otherwise pay a full node scan on every write — and to THIS
+     * setter's keys (D-8: a key an earlier setter of the batch wrote is told
+     * once, #3743). null = no trap writes this batch (bulk paths fall back to
+     * the full scan); WK_ALL = bound unusable (array length write).
+     * LOAD-BEARING SHAPE RULE: array proxy targets carry their fields as named
+     * properties on a real array, and V8
+     * normalizes an array to dictionary properties as the named count grows
+     * (empirically at counts ≡ 0 mod 3 from 18 up on V8 13.x) — every trap
+     * field read then becomes a hash lookup (~15% uibench, tree suites
+     * worst). Future write-side state MUST ride an extension object, not new
+     * named fields. */
+    wk: WrittenKeys | null;
+    /** Lazy deep-witness node: `deep()` subscribes ONE node per record instead
+     * of one per path; write paths bump it only when it exists. Separate from
+     * `k` so $TRACK/mapArray never rerun on leaf value changes (R9). */
+    dk: Signal<number> | null;
+    /** Parent target (path copying walks this at commit). */
+    u: StoreTarget | null;
+    /** Property key of this target in the parent's backing. */
+    pk: PropertyKey | null;
+    /** The proxy for this target (stable outward identity). */
+    px: any;
+    /** Sticky descendants flag (§6d). */
+    d: boolean;
+    /** Sticky accessors-seen flag: an own accessor property was observed on
+     * this target (first-read scan, defineProperty, or clone scan). Gates the
+     * fold diff's descriptor-safe path and the get trap's descriptor path. */
+    a: boolean;
+    /** Accessor scan grade: 0 = not yet scanned (adoption resets — adopted data
+     * is not rescanned until the next draft), 1 = scanned, 2 = scanned and
+     * PLAIN DATA — `Object.prototype` with every own key an enumerable data
+     * property. Grade 2 unlocks the spread clone (cloneRaw), bare-assignment
+     * overlay writes and flatten (#3360); a non-plain defineProperty through
+     * the draft downgrades it to 1. */
+    sc: 0 | 1 | 2;
+    /** Own-key count: exact at scan, then bumped by set-trap writes of keys new
+     * to the container (never decremented — an estimate for the overlay/clone
+     * choice only, #3360). */
+    kc: number;
+    /** Pending backing is a prototype-chain OVERLAY of the committed backing
+     * (`Object.create(v)` — own keys are this batch's writes, everything else
+     * reads through). O(written) per flush instead of O(container) clones
+     * (#3044); commit flattens own keys onto an owned committed backing in
+     * place. Plain-data non-array containers qualify; chained backings and
+     * accessor containers keep the descriptor clone. `materializePB`
+     * downgrades to the clone path when a consumer needs a real container
+     * (draft escape). */
+    ovl: boolean;
+    /** Keys deleted in the overlay window (a prototype overlay cannot shadow
+     * a delete); null when none. */
+    del: Set<PropertyKey> | null;
+    /** Projection family, null for plain stores (§7b). */
+    fam: StoreFamily | null;
+    /** Shallow store root (values served raw). */
+    s: boolean;
+}
+/**
+ * Ownership stamp (#3360): every backing the store ALLOCATES (CoW clones,
+ * privatized committed backings) carries its owning target under this
+ * enumerable symbol. One property write replaces the two weak-collection
+ * registrations (ownership set + raw→target map) a fresh object used to pay
+ * per draft — V8's identity-hash + ephemeron cost dominated the one-key
+ * write floor. Enumerable so a spread copy (the plain-data clone path) stays
+ * on the fast path and carries the stamp along.
+ *
+ * Owned backings are never user-reachable (`snapshot` copies them, the traps
+ * hide the key), so every raw key walk in the store must skip `$OWNER`, and
+ * ownership is answered by `isOwned` — a user object never carries it.
+ * Overlay drafts (`Object.create(v)` over an owned `v`) inherit the stamp.
+ */
+export declare const $OWNER: unique symbol;
+/** raw → target for plain (family-less) stores. Family stores use their own
+ * map so one raw can wrap once per family (§7b). */
+export declare const storeLookup: WeakMap<object, StoreTarget>;
+export declare function setLookup(raw: object, t: StoreTarget): void;
+export declare function isOwned(raw: object): boolean;
+/** The target wrapping `raw` in `fam` (or the plain lookup). An owned raw
+ * answers from its stamp; a user raw from the map. */
+export declare function lookupTarget(raw: object, fam: StoreFamily | null): StoreTarget | undefined;
+/** Test-tier oracle (INTERNALS §5): no write path ever mutates a
+ * user-provided (non-owned) object. */
+export declare const ingestedRaw: WeakSet<object> | null;
+export declare function devAssertNeverUserMutation(target: object): void;
+/** Sticky descendants flag up the parent chain (§6d): adoption descends
+ * into a changed child pair only where a target with nodes exists below. */
+export declare function markDescendants(target: StoreTarget): void;
+/** Observe tier: the owner in scope at `createStore` (attribution names and
+ * owner paths); the `_owner` write never reaches the proxy. */
+export declare const storeOwners: WeakMap<StoreTarget, Owner | null> | null;