@ontrails/store 1.0.0-beta.14 → 1.0.0-beta.16

package/src/types.ts

@@ -1,5 +1,19 @@
+import type { Signal } from '@ontrails/core';
+import type { StoreAccessorProtocol } from '@ontrails/core/store';
 import type { z } from 'zod';
 
+/**
+ * Backend-agnostic persistence shapes that an adapter can interpret.
+ */
+export type StoreKind = 'tabular' | 'document' | 'file' | 'kv' | 'cache';
+
+/**
+ * Store-level options applied to the authored definition.
+ */
+export interface StoreOptions {
+  readonly kind?: StoreKind;
+}
+
 /**
  * Object schema accepted by the store definition layer.
  */
@@ -13,83 +27,176 @@ export type StoreFieldKey<TSchema extends StoreObjectSchema> = Extract<
   string
 >;
 
+type VersionedSchema<
+  TSchema extends StoreObjectSchema,
+  TVersioned extends boolean | undefined,
+> = TVersioned extends true
+  ? TSchema extends z.ZodObject<infer TShape>
+    ? z.ZodObject<TShape & { version: z.ZodNumber }>
+    : never
+  : TSchema;
+
 type GeneratedFieldNames<
   TSchema extends StoreObjectSchema,
-  TGenerated extends readonly StoreFieldKey<TSchema>[] | undefined,
+  TGenerated extends readonly string[] | undefined,
 > = TGenerated extends readonly StoreFieldKey<TSchema>[]
   ? TGenerated[number]
   : never;
 
+// We intentionally use Zod v4's shape-routed object infer helpers here because
+// the public z.input/z.output path widens away the generic equality we need at
+// store/core trail boundaries. These $-prefixed helpers are semi-internal Zod
+// v4 API; that maintenance tradeoff is acceptable here because the public path
+// does not preserve the boundary-proof shape we need.
+type ObjectInputOf<TShape extends z.ZodRawShape> = z.core.$InferObjectInput<
+  TShape,
+  Record<never, never>
+>;
+
+type ObjectOutputOf<TShape extends z.ZodRawShape> = z.core.$InferObjectOutput<
+  TShape,
+  Record<never, never>
+>;
+
 /**
  * Seed row accepted for one table fixture.
  *
  * Generated fields may be supplied explicitly, but they are optional so test
  * fixtures can omit timestamps and similar server-managed values when the mock
  * store can synthesize them.
+ *
+ * Routes input inference through the object's `shape` via a conditional
+ * `infer` so fixture inputs stay structurally aligned with the derived
+ * create/upsert inputs they meet at store/core trail boundaries.
+ *
+ * This is not the same type-level path core's `deriveTrail()` uses — core
+ * still goes through `z.input<TContour>` / `z.output<TContour>` — but at
+ * concrete instantiations it collapses to the same structural fixture shape
+ * while preserving generic equality across the store/core seam.
  */
 export type StoreFixtureInput<
   TSchema extends StoreObjectSchema,
-  TGenerated extends readonly StoreFieldKey<TSchema>[] | undefined =
-    | readonly StoreFieldKey<TSchema>[]
+  TGenerated extends readonly string[] | undefined =
+    | readonly string[]
     | undefined,
-> = Omit<
-  z.input<TSchema>,
-  Extract<GeneratedFieldNames<TSchema, TGenerated>, keyof z.input<TSchema>>
-> &
-  Partial<
-    Pick<
-      z.input<TSchema>,
-      Extract<GeneratedFieldNames<TSchema, TGenerated>, keyof z.input<TSchema>>
-    >
-  >;
+> = [TSchema] extends [z.ZodObject<infer TShape>]
+  ? Omit<
+      ObjectInputOf<TShape>,
+      Extract<
+        GeneratedFieldNames<TSchema, TGenerated>,
+        keyof ObjectInputOf<TShape>
+      >
+    > &
+      Partial<
+        Pick<
+          ObjectInputOf<TShape>,
+          Extract<
+            GeneratedFieldNames<TSchema, TGenerated>,
+            keyof ObjectInputOf<TShape>
+          >
+        >
+      >
+  : never;
 
 /**
  * Normalized fixture row after schema validation and default application.
+ *
+ * Mirror of {@link StoreFixtureInput} on the output side — routed through
+ * `$InferObjectOutput<TShape, Record<never, never>>` so row types stay
+ * structurally aligned with the contour output shapes they compose against.
+ *
+ * As with {@link StoreFixtureInput}, this is a shape-routed equivalent rather
+ * than the identical `z.output<TSchema>` inference path core uses directly.
  */
 export type StoreFixtureRow<
   TSchema extends StoreObjectSchema,
-  TGenerated extends readonly StoreFieldKey<TSchema>[] | undefined =
-    | readonly StoreFieldKey<TSchema>[]
+  TGenerated extends readonly string[] | undefined =
+    | readonly string[]
     | undefined,
-> = Omit<
-  z.output<TSchema>,
-  Extract<GeneratedFieldNames<TSchema, TGenerated>, keyof z.output<TSchema>>
-> &
-  Partial<
-    Pick<
-      z.output<TSchema>,
-      Extract<GeneratedFieldNames<TSchema, TGenerated>, keyof z.output<TSchema>>
-    >
-  >;
+> = [TSchema] extends [z.ZodObject<infer TShape>]
+  ? Omit<
+      ObjectOutputOf<TShape>,
+      Extract<
+        GeneratedFieldNames<TSchema, TGenerated>,
+        keyof ObjectOutputOf<TShape>
+      >
+    > &
+      Partial<
+        Pick<
+          ObjectOutputOf<TShape>,
+          Extract<
+            GeneratedFieldNames<TSchema, TGenerated>,
+            keyof ObjectOutputOf<TShape>
+          >
+        >
+      >
+  : never;
 
 /**
- * Connector-owned search metadata.
+ * Adapter-owned search metadata.
  *
  * The core package keeps this opaque on purpose. Search behavior is declared
- * here and interpreted by a concrete connector later.
+ * here and interpreted by a concrete adapter later.
  */
 export type StoreSearchDefinition = Readonly<Record<string, unknown>>;
 
 /**
- * Authored metadata for one store table.
+ * Change signals projected from one store entity definition.
  */
-export interface StoreTableInput<
+export interface StoreTableSignals<TPayload> {
+  readonly created: Signal<TPayload>;
+  readonly updated: Signal<TPayload>;
+  readonly removed: Signal<TPayload>;
+}
+
+/**
+ * Shared fields for all store table input variants.
+ */
+interface StoreTableInputBase<
   TSchema extends StoreObjectSchema = StoreObjectSchema,
   TGenerated extends readonly StoreFieldKey<TSchema>[] | undefined =
     | readonly StoreFieldKey<TSchema>[]
     | undefined,
+  TVersioned extends boolean | undefined = boolean | undefined,
 > {
-  readonly fixtures?: readonly StoreFixtureInput<TSchema, TGenerated>[];
+  readonly fixtures?: readonly StoreFixtureInput<
+    VersionedSchema<TSchema, TVersioned>,
+    GeneratedFieldsOfShape<TSchema, TGenerated, TVersioned>
+  >[];
   readonly generated?: TGenerated;
+  readonly indexed?: readonly StoreFieldKey<TSchema>[];
   readonly indexes?: readonly StoreFieldKey<TSchema>[];
-  readonly primaryKey: StoreFieldKey<TSchema>;
   readonly references?: Readonly<
     Partial<Record<StoreFieldKey<TSchema>, string>>
   >;
   readonly schema: TSchema;
   readonly search?: StoreSearchDefinition;
+  readonly versioned?: TVersioned;
 }
 
+/**
+ * Authored metadata for one store entity.
+ *
+ * At least one of `identity` or `primaryKey` must be provided. Omitting both
+ * is a compile-time error — `resolveIdentity` would throw at runtime without
+ * this guard.
+ */
+export type StoreTableInput<
+  TSchema extends StoreObjectSchema = StoreObjectSchema,
+  TGenerated extends readonly StoreFieldKey<TSchema>[] | undefined =
+    | readonly StoreFieldKey<TSchema>[]
+    | undefined,
+  TVersioned extends boolean | undefined = boolean | undefined,
+> =
+  | (StoreTableInputBase<TSchema, TGenerated, TVersioned> & {
+      readonly identity: StoreFieldKey<TSchema>;
+      readonly primaryKey?: StoreFieldKey<TSchema>;
+    })
+  | (StoreTableInputBase<TSchema, TGenerated, TVersioned> & {
+      readonly identity?: StoreFieldKey<TSchema>;
+      readonly primaryKey: StoreFieldKey<TSchema>;
+    });
+
 /**
  * Record of authored tables passed to `store(...)`.
  */
@@ -97,25 +204,82 @@ export type StoreTablesInput = Record<
   string,
   StoreTableInput<
     StoreObjectSchema,
-    readonly StoreFieldKey<StoreObjectSchema>[] | undefined
+    readonly StoreFieldKey<StoreObjectSchema>[] | undefined,
+    boolean | undefined
   >
 >;
 
+type DeclaredGeneratedFieldsOfInput<TInput extends StoreTableInput> =
+  TInput['generated'] extends readonly StoreFieldKey<TInput['schema']>[]
+    ? TInput['generated']
+    : readonly [];
+
+type GeneratedFieldsOfShape<
+  TSchema extends StoreObjectSchema,
+  TGenerated extends readonly StoreFieldKey<TSchema>[] | undefined,
+  TVersioned extends boolean | undefined,
+> = TVersioned extends true
+  ? readonly [
+      ...(TGenerated extends readonly StoreFieldKey<TSchema>[]
+        ? TGenerated
+        : readonly []),
+      'version',
+    ]
+  : TGenerated extends readonly StoreFieldKey<TSchema>[]
+    ? TGenerated
+    : readonly [];
+
+type VersionedFieldsOfInput<TInput extends StoreTableInput> =
+  TInput['versioned'] extends true ? true : false;
+
+type SchemaOfInput<TInput extends StoreTableInput> = VersionedSchema<
+  TInput['schema'],
+  VersionedFieldsOfInput<TInput>
+>;
+
 /**
  * Preserve generated fields when present, otherwise normalize to an empty tuple.
  */
 export type GeneratedFieldsOfInput<TInput extends StoreTableInput> =
-  TInput['generated'] extends readonly StoreFieldKey<TInput['schema']>[]
-    ? TInput['generated']
-    : readonly [];
+  GeneratedFieldsOfShape<
+    TInput['schema'],
+    DeclaredGeneratedFieldsOfInput<TInput>,
+    VersionedFieldsOfInput<TInput>
+  >;
+
+/**
+ * Preserve the authored identity field.
+ */
+export type IdentityFieldOfInput<TInput extends StoreTableInput> =
+  TInput['identity'] extends StoreFieldKey<TInput['schema']>
+    ? TInput['identity']
+    : TInput['primaryKey'] extends StoreFieldKey<TInput['schema']>
+      ? TInput['primaryKey']
+      : never;
 
 /**
- * Preserve index fields when present, otherwise normalize to an empty tuple.
+ * Preserve indexed fields when present, otherwise normalize to an empty tuple.
+ *
+ * At runtime `resolveIndexed` merges both `indexed` and `indexes` arrays, so
+ * this type mirrors that behavior: when both are present, the result is the
+ * union of both tuples. When only one is provided, it is used directly.
+ */
+export type IndexedFieldsOfInput<TInput extends StoreTableInput> =
+  TInput['indexed'] extends readonly StoreFieldKey<TInput['schema']>[]
+    ? TInput['indexes'] extends readonly StoreFieldKey<TInput['schema']>[]
+      ? readonly [...TInput['indexed'], ...TInput['indexes']]
+      : TInput['indexed']
+    : TInput['indexes'] extends readonly StoreFieldKey<TInput['schema']>[]
+      ? TInput['indexes']
+      : readonly [];
+
+/**
+ * Backward-compatible alias for code that still uses the SQL-shaped name.
  */
 export type IndexFieldsOfInput<TInput extends StoreTableInput> =
   TInput['indexes'] extends readonly StoreFieldKey<TInput['schema']>[]
     ? TInput['indexes']
-    : readonly [];
+    : IndexedFieldsOfInput<TInput>;
 
 /**
  * Preserve references when present, otherwise normalize to an empty object.
@@ -132,11 +296,11 @@ export type ReferencesOfInput<TInput extends StoreTableInput> =
  */
 export type FixturesOfInput<TInput extends StoreTableInput> =
   TInput['fixtures'] extends readonly StoreFixtureInput<
-    TInput['schema'],
+    SchemaOfInput<TInput>,
     GeneratedFieldsOfInput<TInput>
   >[]
     ? readonly StoreFixtureRow<
-        TInput['schema'],
+        SchemaOfInput<TInput>,
         GeneratedFieldsOfInput<TInput>
       >[]
     : readonly [];
@@ -151,14 +315,18 @@ export interface StoreTable<
   readonly fixtureSchema: StoreObjectSchema;
   readonly fixtures: FixturesOfInput<TInput>;
   readonly generated: GeneratedFieldsOfInput<TInput>;
-  readonly indexes: IndexFieldsOfInput<TInput>;
+  readonly identity: IdentityFieldOfInput<TInput>;
+  readonly indexed: IndexedFieldsOfInput<TInput>;
+  readonly indexes: IndexedFieldsOfInput<TInput>;
   readonly insertSchema: StoreObjectSchema;
   readonly name: TName;
-  readonly primaryKey: TInput['primaryKey'];
+  readonly primaryKey: IdentityFieldOfInput<TInput>;
   readonly references: ReferencesOfInput<TInput>;
-  readonly schema: TInput['schema'];
-  readonly search?: TInput['search'];
+  readonly schema: SchemaOfInput<TInput>;
+  readonly search?: StoreSearchDefinition | undefined;
+  readonly signals: StoreTableSignals<z.output<SchemaOfInput<TInput>>>;
   readonly updateSchema: StoreObjectSchema;
+  readonly versioned: VersionedFieldsOfInput<TInput>;
 }
 
 /**
@@ -170,7 +338,8 @@ export interface StoreDefinition<
   readonly get: <TName extends Extract<keyof TTables, string>>(
     name: TName
   ) => StoreTable<TTables[TName], TName>;
-  readonly kind: 'store';
+  readonly kind: StoreKind;
+  readonly signals: readonly Signal<unknown>[];
   readonly tableNames: readonly Extract<keyof TTables, string>[];
   readonly tables: {
     readonly [TName in keyof TTables]: StoreTable<
@@ -178,12 +347,13 @@ export interface StoreDefinition<
       Extract<TName, string>
     >;
   };
+  readonly type: 'store';
 }
 
 /**
  * Structural view of any normalized store table.
  *
- * This stays broad on purpose so connector packages can accept concrete store
+ * This stays broad on purpose so adapter packages can accept concrete store
  * definitions returned by `store(...)` without erasing their table-specific
  * types back to one canonical generic instantiation.
  */
@@ -191,6 +361,8 @@ export interface AnyStoreTable {
   readonly fixtureSchema: StoreObjectSchema;
   readonly fixtures: readonly Record<string, unknown>[];
   readonly generated: readonly string[];
+  readonly identity: string;
+  readonly indexed: readonly string[];
   readonly indexes: readonly string[];
   readonly insertSchema: StoreObjectSchema;
   readonly name: string;
@@ -198,16 +370,20 @@ export interface AnyStoreTable {
   readonly references: Readonly<Partial<Record<string, string>>>;
   readonly schema: StoreObjectSchema;
   readonly search?: StoreSearchDefinition | undefined;
+  readonly signals: StoreTableSignals<unknown>;
   readonly updateSchema: StoreObjectSchema;
+  readonly versioned: boolean;
 }
 
 /**
  * Structural view of any normalized store definition.
  */
 export interface AnyStoreDefinition {
-  readonly kind: 'store';
+  readonly kind: StoreKind;
+  readonly signals: readonly Signal<unknown>[];
   readonly tableNames: readonly string[];
   readonly tables: Readonly<Record<string, AnyStoreTable>>;
+  readonly type: 'store';
 }
 
 type GeneratedFieldKeysOf<TTable extends AnyStoreTable> = readonly Extract<
@@ -237,9 +413,9 @@ export type FixtureOf<TTable extends AnyStoreTable> = StoreFixtureRow<
 >;
 
 /**
- * Primary-key field name for one store table.
+ * Identity field name for one store entity.
  */
-export type PrimaryKeyOf<TTable extends AnyStoreTable> = TTable['primaryKey'];
+export type IdentityOf<TTable extends AnyStoreTable> = TTable['identity'];
 
 /**
  * Server-managed fields for one store table.
@@ -252,21 +428,39 @@ export type GeneratedKeysOf<TTable extends AnyStoreTable> = Extract<
 /**
  * Insert shape: entity minus generated fields, with defaulted fields optional.
  *
- * Uses `z.input` so that fields with `.default()` are correctly represented as
- * optional in the insert shape (matching the runtime insert schema behavior).
+ * Routes through `$InferObjectInput<TShape, Record<never, never>>` via a
+ * conditional `infer` on the object's `shape`. At concrete instantiations
+ * this collapses to the same structural shape as
+ * `Omit<z.input<TTable['schema']>, GeneratedKeysOf<TTable>>`, but the
+ * shape-routed form lets TypeScript prove structural equality with
+ * `CreateInputOf<Contour, ...>` at trail boundaries without widening
+ * generic call sites to `Record<string, unknown>`.
+ *
+ * Defaulted fields remain optional because `$InferObjectInput` honors
+ * `OptionalInSchema`, mirroring the runtime insert schema behavior.
  */
-export type InsertOf<TTable extends AnyStoreTable> = Omit<
-  z.input<TTable['schema']>,
-  GeneratedKeysOf<TTable>
->;
+export type InsertOf<TTable extends AnyStoreTable> = [
+  TTable['schema'],
+] extends [z.ZodObject<infer TShape>]
+  ? Omit<ObjectInputOf<TShape>, GeneratedKeysOf<TTable>>
+  : never;
 
 /**
  * Update shape: partial insert minus the primary key (immutable identifier).
  */
 export type UpdateOf<TTable extends AnyStoreTable> = Partial<
-  Omit<InsertOf<TTable>, PrimaryKeyOf<TTable>>
+  Omit<InsertOf<TTable>, IdentityOf<TTable>>
 >;
 
+/**
+ * Upsert shape: entity payload with generated fields remaining optional.
+ *
+ * This matches the backend-agnostic "create or replace" contract while
+ * still allowing adapters to synthesize generated values like IDs and
+ * timestamps when the caller omits them.
+ */
+export type UpsertOf<TTable extends AnyStoreTable> = FixtureInputOf<TTable>;
+
 /**
  * Typed filter shape for list operations.
  */
@@ -284,10 +478,10 @@ export interface StoreListOptions {
  * Shared identifier type for read/write accessors.
  */
 export type StoreIdentifierOf<TTable extends AnyStoreTable> =
-  EntityOf<TTable>[Extract<PrimaryKeyOf<TTable>, keyof EntityOf<TTable>>];
+  EntityOf<TTable>[Extract<IdentityOf<TTable>, keyof EntityOf<TTable>>];
 
 /**
- * Access mode for a bound store connection or provision.
+ * Access mode for a bound store connection or resource.
  */
 export type StoreAccessMode = 'readonly' | 'readwrite';
 
@@ -295,7 +489,7 @@ export type StoreAccessMode = 'readonly' | 'readwrite';
  * Read-only table operations that every bound store must expose.
  */
 export interface ReadOnlyStoreTableAccessor<TTable extends AnyStoreTable> {
-  /** Retrieve a single entity by primary key. Returns `null` when not found. */
+  /** Retrieve a single entity by identity. Returns `null` when not found. */
   get(id: StoreIdentifierOf<TTable>): Promise<EntityOf<TTable> | null>;
   /**
    * List entities, optionally filtered. Returns all rows when no filters are
@@ -308,33 +502,91 @@ export interface ReadOnlyStoreTableAccessor<TTable extends AnyStoreTable> {
 }
 
 /**
- * Writable table operations layered on top of the read contract.
+ * Backend-agnostic writable operations layered on top of the read contract.
  */
-export interface StoreTableAccessor<
+export interface StoreAccessor<
   TTable extends AnyStoreTable,
 > extends ReadOnlyStoreTableAccessor<TTable> {
   /**
-   * Insert a new entity.
+   * Create or replace one entity using the store's identity field.
    *
    * @throws {AlreadyExistsError} On primary key or unique constraint violation.
    *
    * @remarks
-   * This is an intentional throw-based boundary: store connectors throw typed
+   * This is an intentional throw-based boundary: store adapters throw typed
    * errors (`AlreadyExistsError`) rather than returning `Result`. Trail
    * implementations that call store accessors should catch and convert to
-   * `Result.err()` at their level. A future `safeInsert` returning `Result`
-   * is planned but deferred to avoid cascading changes across all connectors.
+   * `Result.err()` at their level. A future safe variant returning `Result`
+   * is planned but deferred to avoid cascading changes across all adapters.
    */
-  insert(input: InsertOf<TTable>): Promise<EntityOf<TTable>>;
+  upsert(input: UpsertOf<TTable>): Promise<EntityOf<TTable>>;
   /**
-   * Remove an entity by primary key. Returns `{ deleted: true }` when the
+   * Remove an entity by identity. Returns `{ deleted: true }` when the
    * row was found and removed, `{ deleted: false }` when no matching row
    * existed (not an error).
    */
   remove(id: StoreIdentifierOf<TTable>): Promise<{ readonly deleted: boolean }>;
+}
+
+// ---------------------------------------------------------------------------
+// Compile-time assertion: StoreAccessor satisfies the core accessor protocol.
+//
+// `@ontrails/core/store` declares a structural protocol that `deriveTrail()`
+// uses to synthesize default blazes without importing `@ontrails/store`. We
+// pin the relationship here rather than in core so that any drift between
+// the two shapes fails the store build immediately. If this check fails, the
+// protocol in core has diverged from the store accessor contract — fix the
+// protocol shape, not this assertion.
+// ---------------------------------------------------------------------------
+
+type AssertExtends<TActual, TExpected> = TActual extends TExpected
+  ? true
+  : never;
+
+/**
+ * Pins the structural relationship between `StoreAccessor` and the core
+ * `StoreAccessorProtocol`. If this check resolves to `never`, the protocol in
+ * core has drifted from the store accessor contract — fix the protocol shape,
+ * not this assertion.
+ */
+const storeAccessorProtocolCheck: AssertExtends<
+  StoreAccessor<AnyStoreTable>,
+  StoreAccessorProtocol<
+    UpsertOf<AnyStoreTable>,
+    EntityOf<AnyStoreTable>,
+    StoreIdentifierOf<AnyStoreTable>,
+    FiltersOf<AnyStoreTable>
+  >
+> = true;
+
+void storeAccessorProtocolCheck;
+
+/**
+ * Tabular writable operations layered on top of the backend-agnostic
+ * contract.
+ */
+export interface StoreTableAccessor<
+  TTable extends AnyStoreTable,
+> extends StoreAccessor<TTable> {
+  /**
+   * Insert a new entity.
+   *
+   * Tabular adapters can expose this convenience when the backend has a
+   * native distinction between create and update.
+   */
+  insert(input: InsertOf<TTable>): Promise<EntityOf<TTable>>;
   /**
-   * Patch an entity by primary key with partial fields. Returns the updated
+   * Patch an entity by identity with partial fields. Returns the updated
    * entity, or `null` when no row with that ID exists.
+   *
+   * @remarks
+   * On versioned tables, `update` does **not** participate in optimistic
+   * concurrency control. The `UpdateOf<TTable>` shape is derived by omitting
+   * generated fields — including the framework-managed `version` column — so
+   * any `version` value is dropped before reaching the adapter and the
+   * adapter always auto-increments without comparing. Callers that need
+   * lost-update protection must use {@link StoreAccessor.upsert | `upsert`}
+   * instead and pass the expected `version` in the payload.
    */
   update(
     id: StoreIdentifierOf<TTable>,
@@ -352,10 +604,51 @@ export type ReadOnlyStoreConnection<TStore extends AnyStoreDefinition> = {
 };
 
 /**
- * Connection shape exposed by a writable bound store.
+ * Backend-agnostic connection shape exposed by a writable bound store.
  */
 export type StoreConnection<TStore extends AnyStoreDefinition> = {
+  readonly [TName in keyof TStore['tables']]: StoreAccessor<
+    TStore['tables'][TName]
+  >;
+};
+
+/**
+ * Tabular connection shape exposed by adapters that distinguish insert and
+ * patch operations from the generalized `upsert` contract.
+ */
+export type StoreTableConnection<TStore extends AnyStoreDefinition> = {
   readonly [TName in keyof TStore['tables']]: StoreTableAccessor<
     TStore['tables'][TName]
   >;
 };
+
+/**
+ * Optional fixture overrides used when building a mock store connection.
+ *
+ * The shape is a partial map keyed by table name; each entry is a list of
+ * fixture inputs validated against the table's fixture schema. Adapters
+ * share this type so every store backend seeds mocks the same way.
+ */
+export type StoreMockSeed<TDef extends AnyStoreDefinition> = Partial<{
+  readonly [TName in keyof TDef['tables']]: readonly FixtureInputOf<
+    TDef['tables'][TName]
+  >[];
+}>;
+
+/**
+ * Shared adapter options every store backend accepts.
+ *
+ * Concrete adapters extend this shape with their backend-specific fields
+ * (e.g. `url`, `dir`). Aligning the authored surface here lets the framework
+ * reason about adapter options uniformly — one shape, many projections.
+ */
+export interface StoreAdapterOptions<TDef extends AnyStoreDefinition> {
+  /** Optional resource id override. Defaults to `"store"`. */
+  readonly id?: string;
+  /** Human-readable description surfaced on the resource definition. */
+  readonly description?: string;
+  /** Free-form metadata for downstream tooling and governance. */
+  readonly meta?: Record<string, unknown>;
+  /** Optional per-table fixture overrides used by the mock resource factory. */
+  readonly mockSeed?: StoreMockSeed<TDef>;
+}

package/.agents/notes/2026-04-04/handoff-202604032309-9e85a104.md

@@ -1,38 +0,0 @@
----
-created: 2026-04-04T03:09:15.424Z
-type: handoff
-session: 9e85a104-864f-4273-b68d-a4a95eb2d5fc
----
-
-# Handoff 2026-04-04 23:09
-
-> Session `9e85a104` — PR feedback loop on 14-branch Graphite stack (#64-#77)
-
-## Done
-
-- **Round 1**: Fixed 11 P1s across the stack — `persistEstablishedTopoSave` throw→Result, hash pipeline unification in drift.ts, store type safety (nullable defaults, PK leak, InsertOf/UpdateOf precision), drizzle error mapping, legacy tracker DB cleanup, transitive cache TSDoc, duplicate const before compile error
-- **Round 2**: Fixed absorb regressions (variable reference splits across branches), plus new P1s — Commander undefined opts, toTrackStore close() no-op, verifyCurrentTopo hash pipeline, duplicate verifyCurrentTopo removal
-- **Round 3**: Fixed remaining P1s — ADR depends_on slug→integer normalization, draft-promote preflight rename validation (duplicates + existing targets), NOT NULL on PK columns in generated SQL, InternalError passthrough, warden README method names (.trailhead→.blaze), vocabulary verb fix
-- **Thread resolution**: 128 threads resolved across 3 rounds, re-reviews requested each time
-- **Key learning**: `gt absorb` splits changes across branches unpredictably when a function definition and its callers span different branches — always walk up and typecheck each branch after absorb
-
-## State
-
-- On branch `trl-129-topo-and-dev-surfaces` (#69) with an uncommitted fix (drift.ts resolveTrailsDir import + readTrailheadLock dir fix) — lint failed, needs investigation
-- 4 new P1s surfaced in Round 4 (from `-p 2` run which includes P0-P2):
-  - **#69**: drift.ts passes workspace root instead of `.trails/` to readTrailheadLock (fix attempted, lint error pending)
-  - **#71**: v2→v3 migration gap in topo-saves.ts — crash on existing schema version 2 databases
-  - **#72**: createMockTopoStore returns data without seeded saves (diverges from real store)
-  - **#77**: Three broken API examples in warden README (wrong signatures, invalid lefthook key)
-- P2s not yet addressed across #65, #68, #70, #72, #75
-
-## Next
-
-- [ ] Debug lint failure on #69 drift.ts fix and commit
-- [ ] Fix #71: Add v2→v3 migration guard in `ensureTopoHistorySchema` to create `topo_schemas`/`topo_exports` tables
-- [ ] Fix #72: Add empty-save guard to `createMockTopoStore` `trails.list()`/`trails.get()`
-- [ ] Fix #77: Correct `runWarden` and `checkDrift` signatures + lefthook key in warden README
-- [ ] Walk up all branches verifying typecheck after each fix
-- [ ] Submit stack, resolve threads, write loop record
-- [ ] Then address P2s: gitignore duplicate-append (#68), stale TSDoc (#70), test harness fallback (#65), readonlyStore mock factory (#75)
-- [ ] Consider: the `isDraftMarkedFile` vs `stripDraftFileMarkers` inconsistency on #67 is still open (P2)

package/.turbo/turbo-build.log

@@ -1 +0,0 @@
-$ tsc -b