@solidjs/signals 2.0.0-rc.13 → 2.0.0-rc.14

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

@@ -1,147 +1,169 @@
-import { type Signal } from "../core/index.js";
-import type { Refreshable } from "../core/index.js";
-/** A reactive view of a store's value. Update it through the paired `StoreSetter`. */
-export type Store<T> = 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(fn, seed, { key })` — 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, options?)` 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>];
-/** Options shared by all store primitives. */
-export interface StoreOptions {
-    /**
-     * Debug name (dev and observe builds). Property nodes are labelled
-     * `<name>.<key>` in attribution output (`todos.title`); a derived store's
-     * projection node carries the name itself.
-     */
-    name?: string;
-    /** Single-layer store: root keys reactive, values raw records replaced by reference */
-    shallow?: boolean;
+import type { Signal } from "../core/types.js";
+import { type StoreFamily, type StoreTarget } from "./target.js";
+/** The optimistic machinery (optimistic.ts, S4), installed when it loads
+ * — a plain store pays nothing for it (#2883): the plain paths reach it
+ * only through a family with `opt` set, which only `createOptimisticStore`
+ * sets. */
+export interface OptHooks {
+    /** A user setter's draft on an optimistic family: a clone of the
+     * writer's view (a staging already on the target is set aside). */
+    draft(t: StoreTarget): Record<PropertyKey, any>;
+    /** The setter's exit: the draft becomes guesses; returns the staging the
+     * draft set aside (`null`: none). */
+    writes(t: StoreTarget, pb: Record<PropertyKey, any>): Record<PropertyKey, any> | null;
+    /** `src` with the lanes' values over it (`writer`: the next write's base
+     * — the unflushed guesses too). */
+    view(t: StoreTarget, src: Record<PropertyKey, any>, writer?: boolean): Record<PropertyKey, any>;
+    /** An untracked `key in store`: the presence guess, or `undefined`. */
+    has(t: StoreTarget, key: PropertyKey): boolean | undefined;
+    /** A guessed key's descriptor (`null`: removed; `undefined`: no guess). */
+    descriptor(t: StoreTarget, key: PropertyKey): PropertyDescriptor | null | undefined;
+    /** The flush's commit: targets no lane holds leave `overlaid`. */
+    sweep(): void;
+    /** The container comparator's lane arm: an arrangement guess against a
+     * landing (or another arrangement), by row identity. */
+    arrangement(t: StoreTarget, a: any, b: any): boolean;
+    /** A user's `reconcile` on an optimistic family: the keyed diff written
+     * into the draft. */
+    reconcile(draft: any, incoming: any, keyFn: ((item: any) => any) | null): void;
 }
-/**
- * Options for derived/projected stores created with
- * `createStore(fn, seed, options?)`, `createProjection(fn, seed, options?)`,
- * or `createOptimisticStore(fn, seed, options?)`.
- */
-export interface ProjectionOptions extends StoreOptions {
-    /** Key property name or function for reconciliation identity; `null` merges positionally */
-    key?: string | ((item: NonNullable<any>) => any) | null;
-    /**
-     * 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;
+export declare let optHooks: OptHooks | null;
+export declare function installOptHooks(hooks: OptHooks): void;
+/** The store half of `affects()` (store/affects.ts), installed with the
+ * stores: a node born on a covered record inherits the live mark; an
+ * untracked verdict probe through a record with no node is witnessed. */
+export interface AffectsHooks {
+    born(t: StoreTarget, node: Signal<any>, key: PropertyKey): void;
+    witness(t: StoreTarget, key: PropertyKey | undefined): void;
 }
-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, $RECORD: 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 declare let affectsHooks: AffectsHooks | null;
+export declare function installAffectsHooks(hooks: AffectsHooks): void;
+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 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): 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.
  *
- * @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>;
+/** 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,151 @@
+/**
+ * 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>;
+    /** 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>;
+    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;
+}
+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 since the last 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. 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: Set<PropertyKey> | 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;

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

@@ -0,0 +1,84 @@
+/**
+ * Store — public types, brand symbols, wrappability and raw marking. Shared
+ * by every store module; carries no reactive machinery of its own.
+ */
+import type { Refreshable } from "../core/index.js";
+/** A reactive view of a store's value. Update it through the paired `StoreSetter`. */
+export type Store<T> = 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(fn, seed, { key })` — 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, options?)` 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>];
+/** Options shared by all store primitives. */
+export interface StoreOptions {
+    /**
+     * Debug name (dev and observe builds). Property nodes are labelled
+     * `<name>.<key>` in attribution output (`todos.title`); a derived store's
+     * projection node carries the name itself.
+     */
+    name?: string;
+    /** Single-layer store: root keys reactive, values raw records replaced by reference */
+    shallow?: boolean;
+}
+/**
+ * Options for derived/projected stores created with
+ * `createStore(fn, seed, options?)`, `createProjection(fn, seed, options?)`,
+ * or `createOptimisticStore(fn, seed, options?)`.
+ */
+export interface ProjectionOptions extends StoreOptions {
+    /** Key property name or function for reconciliation identity; `null` merges positionally */
+    key?: string | ((item: NonNullable<any>) => any) | null;
+    /**
+     * 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;
+}
+export type NoFn<T> = T extends Function ? never : T;
+/** Brand keys the proxy answers directly (never user data). */
+export declare const $TRACK: unique symbol, $TARGET: unique symbol, $PROXY: unique symbol, $RECORD: unique symbol;
+export declare namespace SolidStore {
+    interface Unwrappable {
+    }
+}
+export type NotWrappable = string | number | bigint | symbol | boolean | Function | null | undefined | SolidStore.Unwrappable[keyof SolidStore.Unwrappable];
+export declare let rawValuesUsed: boolean;
+export declare function isRawValue(value: any): boolean;
+/** Mark a value so no store ever wraps it (sticky; it reads as a leaf). */
+export declare function markRaw<T>(value: T): T;
+/** A shallow store's ingested record: raw by contract (values served
+ * verbatim, slots replaced by reference). */
+export declare function markRawOne(v: any): void;
+export declare function markRawIngest(container: any): void;
+/** Plain objects and arrays wrap; class instances, DOM nodes, frozen objects
+ * and markRaw'd values are leaves. Per-prototype verdict cached. */
+export declare function isWrappable<T>(obj: T | NotWrappable): obj is T;
+export declare function ownEnumerableKeys(o: object): (string | symbol)[];
+export declare let writeOverride: boolean;
+export declare function setWriteOverride(value: boolean): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidjs/signals",
-  "version": "2.0.0-rc.13",
+  "version": "2.0.0-rc.14",
   "description": "Solid's reactive primitives: signals, memos, effects, stores, and async-aware computations.",
   "author": "Ryan Carniato",
   "license": "MIT",