@storystick/preview 0.0.0-stage → 0.2.0-rc.0

package/dist/runtime/schema-store.d.ts

@@ -0,0 +1,121 @@
+/**
+ * ADR-131 Amendment 002 — iframe-side schema store.
+ *
+ * Caches the project schema fetched via the existing
+ * `/api/q/schemas/current` HTTP route. Two storage layers :
+ *
+ *   1. In-memory `inMemory` cell (sync read for the resolver hot path).
+ *   2. IndexedDB cache, keyed by
+ *      `(projectId, codeVersion, wireFormatVersion)`, TTL 5 min.
+ *
+ * Hot path (`peekSchema`) is synchronous — returns the in-memory record
+ * or `null`. The async `bootSchema` is idempotent : concurrent callers
+ * share a single in-flight promise ; tag mismatches (different
+ * projectId or codeVersion) invalidate the fast path and refetch ;
+ * TTL expiry triggers refetch ; network failures preserve the last
+ * good record (degraded mode).
+ *
+ * Race contracts :
+ *   - Provider mounts AFTER iframe runtime starts → bootSchema returns
+ *     `null` until `previewRuntime.httpClient` is set. Resolver retries
+ *     next rAF cycle. Cost : ~1-2 rAF (~32 ms).
+ *   - codeVersion drift mid-session → resolver detects mismatch, calls
+ *     `resetSchemaStore()` then `bootSchema()` ; null SnapshotItems for
+ *     the cycle, fresh fetch next.
+ *   - Concurrent callers → `inflight` promise serialises ; IDB + HTTP
+ *     caches absorb the rare double-fetch.
+ *
+ * TTL+codeVersion tradeoff (amendment §6.3) : a `storystick push`
+ * without code rebuild leaves the codeVersion unchanged. The iframe
+ * may serve a stale schema for up to 5 min in that edge case. The
+ * normal dev workflow (push → generate types → rebuild → bundle hash
+ * changes → codeVersion bumps) invalidates immediately.
+ */
+import { type RawSchemaRow } from '@storystick/client/adapter';
+export interface CachedSchemaRecord {
+    projectId: string;
+    codeVersion: string;
+    schema: RawSchemaRow;
+    fetchedAt: number;
+}
+export interface SchemaDeliveryFailure {
+    readonly kind: 'transient' | 'incompatible';
+    readonly code: string;
+    readonly message: string;
+    readonly retryable: boolean;
+    readonly projectId: string;
+    readonly codeVersion: string;
+}
+/**
+ * Synchronous accessor — the resolver §D6.1 calls this every rAF cycle.
+ * Returns `null` until `bootSchema()` has resolved at least once with
+ * a non-null gateway response.
+ *
+ * Tag-aware (codex R3 P1) : returns the in-memory record only when its
+ * tags still match the current `(projectId, codeVersion)`. Without
+ * this gate, an identity Replace or codeVersion bump would leak the
+ * prior tenant's / prior bundle's schema to the resolver hot path
+ * until `bootSchema()` has had a chance to overwrite or null-out the
+ * slot. Returning `null` under stale tags is the same surface the
+ * resolver already handles (degraded mode, retry next rAF).
+ */
+export declare function peekSchema(): CachedSchemaRecord | null;
+/**
+ * Boot or refresh the iframe-side schema cache. Returns the in-memory
+ * record (possibly stale, if a refetch failed) OR `null` if no record
+ * has ever been established AND the current attempt cannot proceed
+ * (missing httpClient / identity / codeVersion / network failure).
+ *
+ * Idempotent : concurrent callers await the same `inflight` promise.
+ *
+ * Tag-stability invariant (codex R1 fix) : we re-read the current
+ * projectId + codeVersion AFTER each await and discard the result
+ * if the tags drifted. Without this, an identity Replace mid-flight
+ * could install a wrong-tenant schema OR keep a stale prior record
+ * referenced under the wrong tags.
+ */
+export declare function bootSchema(): Promise<CachedSchemaRecord | null>;
+/**
+ * Drop the in-memory record. Used by the resolver when it detects a
+ * codeVersion drift — the next `bootSchema()` refetches against the
+ * new tag. Does NOT clear IDB ; the IDB entry under the new tag is
+ * separate and the old tag's row is harmless until it ages out.
+ */
+export declare function invalidateSchema(): void;
+/**
+ * Test hook — clears in-memory, in-flight, AND IDB. Never invoked in
+ * production code.
+ */
+export declare function _resetSchemaStoreForTestsOnly(): Promise<void>;
+/**
+ * Test hook — expose the current in-flight promise so tests can assert
+ * concurrent callers share it. Returns null when no fetch is pending.
+ */
+export declare function _peekInflightForTestsOnly(): Promise<CachedSchemaRecord | null> | null;
+export declare function _peekSchemaFailureForTestsOnly(): SchemaDeliveryFailure | null;
+/**
+ * Start the schema-retry orchestrator. Idempotent — calling a second
+ * time before stop returns the same teardown. Wired by `boot.ts` once
+ * per runtime boot.
+ *
+ * Behaviour per §9.T7 :
+ *   - Subscribes to `previewRuntime` ; resets the cycle whenever
+ *     `httpClient` or `identity.projectId` changes ; kicks off attempt
+ *     1 (after the 1s grace delay) when both preconditions are met.
+ *   - If preconditions are ALREADY met at start, schedules attempt 1
+ *     immediately via the same delay path (no fast-track).
+ *   - On success at any attempt, resets the counter ; on attempt 5
+ *     failure, emits the error envelope and stops retrying for the
+ *     current cycle (waiting for the next identity change to rearm).
+ */
+export declare function startSchemaRetryLoop(): () => void;
+export declare function stopSchemaRetryLoop(): void;
+/** Test hook — read the current attempt count. */
+export declare function _peekRetryAttemptForTestsOnly(): number;
+/**
+ * Test hook — directly install an in-memory schema record. Used by
+ * orchestrator tests that need `bootSchema()` to return a record via
+ * the fast path without going through the IDB+transport stack (which
+ * doesn't compose with `vi.useFakeTimers`).
+ */
+export declare function _setInMemoryForTestsOnly(record: CachedSchemaRecord | null): void;