@vibesdotdev/storage 0.0.2 → 1.0.0-rc.3

package/dist/docs/sync.docs.descriptor.js

@@ -2,261 +2,251 @@ const descriptor = {
     kind: 'docs/topic',
     id: 'storage.sync',
     title: 'Storage Sync',
-    summary: 'Cross-app synchronization, cloud-api adapter, and ownerApp pattern',
+    summary: 'storage/sync-bridge wiring, cloud-api adapter, and ownerApp pattern',
     body: {
         type: 'markdown',
         sourceType: 'raw',
         source: `---
 title: Storage Sync
-summary: Cross-app synchronization, cloud-api adapter, and ownerApp pattern
+summary: storage/sync-bridge wiring, cloud-api adapter, and ownerApp pattern
 tags: [storage, sync, cloud-api, ownerApp, synchronization]
 parent: storage
 order: 3
-surfaces: [cli, web, in-app]
-hardware: [consumer, cloud]
+surfaces: [cli]
+hardware: [consumer]
 ---
 
 # Storage Sync
 
-Storage sync enables bidirectional synchronization of data between local storage and remote cloud storage. The \`storage/sync-bridge\` runtime kind declares which manifests should sync and how conflicts are resolved.
-
-## Sync Architecture
-
-\`\`\`
-┌─────────────────┐         ┌──────────────────┐
-│  Local Storage  │◄───────►│  Cloud Storage   │
-│  (libsql/D1)    │  sync   │  (cloud-api)     │
-└─────────────────┘         └──────────────────┘
-       │                           │
-       │                           │
-┌─────────────────┐         ┌──────────────────┐
-│  App A          │         │  App B           │
-│  (consumer)     │         │  (cloud)         │
-└─────────────────┘         └──────────────────┘
-\`\`\`
+Storage sync moves data between local descriptors (a runtime kind) and a
+remote cloud CRUD API. A \`storage/sync-bridge\` descriptor declares which
+entities move and how conflicts are handled; the \`SyncBridge\` executor,
+the record bridges synthesized from \`storage/record\` metadata, and the
+manifest pull/push paths carry it out. A bridge declares wiring only: when
+it runs is owned by the caller (the CLI, a daemon command, or a Workers
+job the app declares). The bridge itself keeps no schedule.
 
 ## Sync Bridge Declaration
 
-Declare which manifests should sync:
-
 \`\`\`ts
-import type { SyncBridgeDescriptor } from '@vibesdotdev/storage';
+import type { SyncBridgeDescriptor } from '@vibesdotdev/storage/schemas/sync-bridge-descriptor';
 
 const syncBridge: SyncBridgeDescriptor = {
   kind: 'storage/sync-bridge',
   id: 'app.settings.sync',
-  title: 'App Settings Sync',
-  manifests: [
-    'app/settings',
-    'app/preferences',
-    'app/theme'
-  ],
-  ownerApp: 'settings-web',
-  conflictResolution: 'local-wins',
-  schedule: {
-    type: 'interval',
-    intervalMs: 300_000  // 5 minutes
-  }
+  name: 'App Settings Sync',
+  source: {
+    // The runtime kind id to collect local descriptors from.
+    runtimeKind: 'app/settings',
+  },
+  target: {
+    // Collection endpoint; entityPath/listField/totalField are optional.
+    apiPath: '/api/app/settings',
+  },
+  sync: {
+    direction: 'bidirectional',
+    ownershipFilter: 'all',
+    conflictStrategy: 'local-wins',
+    sensitiveFields: [],
+    idField: 'id',
+  },
 };
 \`\`\`
 
+The \`source\`/\`target\`/\`sync\` fields are the whole declaration. Optional
+hooks refine it: \`toRemote\`/\`fromRemote\` map shapes, \`collect\` overrides
+collection, \`beforePush\`/\`deleteRemote\` prepare the remote side, and
+\`storageManifestId\`/\`writePulled\` persist pulled items locally.
+
+Storage records do not need a hand-written bridge: a record that is enabled,
+allows \`storage.cloud-api\`, and declares remote CRUD metadata is picked up
+automatically through its synthesized bridge.
+
 ## Sync State
 
-Sync state tracks the synchronization status:
+Sync state persists per-manifest tracking as ManifestSyncState
+(src/sync/schemas/sync-state.ts, re-exported through
+@vibesdotdev/storage/sync/sync-state.consumer):
 
 \`\`\`ts
-interface SyncState {
-  manifests: {
-    [manifestId: string]: {
-      localHash: string | null;
-      remoteHash: string | null;
-      lastSyncedAt: string;
-      syncStatus: 'in-sync' | 'local-ahead' | 'remote-ahead' | 'conflict' | 'error';
-      errorMessage?: string;
-    };
-  };
-  lastSyncAt: string;
-  syncStatus: 'idle' | 'syncing' | 'error';
-}
+import type { ManifestSyncState } from '@vibesdotdev/storage/sync/sync-state.consumer';
+
+// Shape (nullable hashes/dates, optional hashVersion, SyncStatus union):
+// {
+//   manifestId: string;
+//   localHash: string | null;
+//   remoteHash: string | null;
+//   hashVersion?: number;
+//   lastLocalChange: string | null;
+//   lastRemoteChange: string | null;
+//   lastSyncAt: string | null;
+//   lastSyncDirection: 'push' | 'pull' | null;
+//   syncStatus: 'in-sync' | 'local-ahead' | 'remote-ahead' | 'conflict' | 'paused' | 'never-synced';
+//   errorMessage: string | null;
+// }
 \`\`\`
 
+When local and remote hashes diverge from the prior sync point the entry is
+marked \`conflict\` — never auto-merged. A recovered target clears its prior
+error on the next successful probe. The substrate (browser localStorage-backed
+state or the consumer \`{vibesHome}/sync-state.json\` store) resolves through
+the \`storage/sync-state\` runtime kind for the owning runtime — callers never
+select it by surface. Consumer hosts compose
+\`@vibesdotdev/storage/storage.consumer.plugin\` alongside the universal plugin;
+Storage's CLI, TUI and explorer consumer plugins compose it automatically.
+Worker hosts may use \`@vibesdotdev/plugins/core/consumer.plugin\`.
+The universal plugin owns the browser loader and runtime clients; consumer
+persistence and record-delivery reconciliation loaders live only in the consumer
+slice. Repeated composition uses the same plugin id.
+
 ## Manual Sync Operations
 
 ### Pull from Cloud
 
 \`\`\`bash
-vibes storage sync pull --manifest app/settings
+vibes storage sync pull [manifest-id] [--force] [--dry-run] [--json]
 \`\`\`
 
 **Behavior:**
 - Fetches remote data
 - Validates against local schema
-- Overwrites local data if remote is newer
-- Handles conflicts based on resolution strategy
+- Overwrites local data only when remote is newer (or with \`--force\`)
+- Marks \`conflict\` when both sides changed since the last sync
 
 ### Push to Cloud
 
 \`\`\`bash
-vibes storage sync push --manifest app/settings
+vibes storage sync push [manifest-id] [--force] [--dry-run] [--json]
 \`\`\`
 
 **Behavior:**
 - Serializes local data
-- Uploads to cloud-api endpoint
-- Updates sync state with remote hash
-- Handles upload errors gracefully
+- Uploads to the cloud-api endpoint
+- Updates sync state with the remote hash
+- Marks \`conflict\` rather than overwriting a diverged remote
 
 ### Check Sync Status
 
 \`\`\`bash
-vibes storage sync status
+vibes storage sync status [--json]
 \`\`\`
 
-**Output:**
-\`\`\`
-Manifest          Status        Last Synced
-─────────────────────────────────────────────
-app/settings      in-sync       2 minutes ago
-app/preferences   local-ahead   1 hour ago
-app/theme         conflict      3 hours ago
-\`\`\`
+Targets reporting an error or a conflict fail the command
+(\`UNAVAILABLE\` / \`storage-sync-unhealthy\`); under \`--json\` stdout stays
+one document and the failing targets are named in its details.
 
 ### Resolve Conflicts
 
 \`\`\`bash
-vibes storage sync resolve --manifest app/theme --strategy local-wins
+vibes storage sync resolve <manifest-id> --keep <local|remote> [--json]
 \`\`\`
 
 **Conflict strategies:**
-- \`local-wins\` — Keep local data, overwrite remote
-- \`remote-wins\` — Keep remote data, overwrite local
-- \`merge\` — Attempt automatic merge (if possible)
-- \`manual\` — Mark for manual resolution
+- \`--keep local\` — Re-push local data, mark in-sync
+- \`--keep remote\` — Re-pull remote data, mark in-sync
+
+There is no automatic merge: every conflict needs this explicit choice.
+
+Machine contract for pull/push (\`--json\` / \`--format json\`): stdout is a
+single JSON document (a results array, or the \`CapabilityError\` envelope on
+failure) and the exit is non-zero when any target reports error or conflict,
+including dry runs.
 
 ## Cloud-API Adapter
 
-The cloud-api adapter enables remote storage access:
+The cloud-api adapter enables remote storage access. Compose its plugin
+object; it takes no options:
 
 \`\`\`ts
-import { storageAdapterCloudApiPlugin } from '@vibesdotdev/storage-adapter-cloud-api';
-
-await runtime.registerPlugin(storageAdapterCloudApiPlugin({
-  baseUrl: 'https://storage.vibes.dev',
-  authToken: process.env.CLOUD_AUTH_TOKEN,
-  endpoints: {
-    'app/settings': 'https://storage.vibes.dev/app/settings',
-    'app/preferences': 'https://storage.vibes.dev/app/preferences'
-  }
-}));
+import { storageAdapterCloudApiPlugin } from '@vibesdotdev/storage/adapters/cloud-api/plugin';
+
+// \`runtime\` is the VibesRuntime handed to your host entry.
+await runtime.registerPlugin(storageAdapterCloudApiPlugin);
 \`\`\`
 
 ### Endpoint Registration
 
-Manifests can declare their own cloud endpoints:
+Manifests declare their own cloud endpoint through adapter config:
 
 \`\`\`ts
-const settingsManifest: StorageManifestDescriptor = {
+import { z } from 'zod/v4';
+import { StorageManifestDescriptorSchema } from '@vibesdotdev/storage/schemas';
+
+const SettingsSchema = z.object({
+  theme: z.enum(['light', 'dark']),
+  updatedAt: z.string(),
+});
+
+const settingsManifest = StorageManifestDescriptorSchema.parse({
   kind: 'storage/manifest',
   id: 'app/settings',
   namespace: 'app',
+  schema: SettingsSchema,
+  allowedAdapters: ['storage.cloud-api'],
   adapterConfig: {
     'storage.cloud-api': {
-      endpoint: 'https://storage.vibes.dev/app/settings'
-    }
-  }
-};
+      endpoint: '/api/app/settings',
+      ownerApp: 'platform',
+    },
+  },
+});
 \`\`\`
 
+The endpoint is the collection path on the owning app — never an absolute
+URL. The origin comes from the explicit apiEndpoint, else from the
+owning app's declared \`infra/service\` target on the handed runtime, and
+the bearer comes through the runtime's credential owner — never a manifest field.
+
 ## OwnerApp Pattern
 
-The \`ownerApp\` field declares which app owns the canonical data:
+The \`ownerApp\` field names the app whose \`infra/service\` origin is the
+sync target (default \`'knowledge'\`):
 
 \`\`\`ts
 {
-  ownerApp: 'settings-web'  // This app's data is canonical
+  ownerApp: 'platform'
 }
 \`\`\`
 
 **Implications:**
-- Owner app's data is the source of truth
-- Conflicts default to owner's version
-- Other apps sync from owner
-- Owner app handles conflict resolution
+- The named service's origin is the sync target for this bridge
+- An undeclared service resolves to \`unknown\` and the run refuses instead of pushing anywhere
+- It does not make the owner's data canonical and never auto-resolves conflicts
 
 ## Sync Scheduling
 
-### Interval-Based Sync
-
-\`\`\`ts
-{
-  schedule: {
-    type: 'interval',
-    intervalMs: 300_000  // 5 minutes
-  }
-}
-\`\`\`
-
-### Event-Triggered Sync
-
-\`\`\`ts
-{
-  schedule: {
-    type: 'on-change',
-    debounceMs: 5000  // wait 5s after last change
-  }
-}
-\`\`\`
-
-### Manual Sync Only
-
-\`\`\`ts
-{
-  schedule: {
-    type: 'manual'  // only sync when explicitly triggered
-  }
-}
-\`\`\`
+Bridges declare no schedule. To run sync on a timer or event, declare a
+Workers job or flow in the owning app that invokes the sync entrypoint, and
+let the runtime lifecycle own retries and cancellation. Hosts also call sync
+after local writes, authentication, reconnect, and foreground resume.
 
 ## Dry-Run Mode
 
 Test sync behavior without making changes:
 
 \`\`\`bash
-vibes storage sync pull --manifest app/settings --dry-run
+vibes storage sync pull app/settings --dry-run
 \`\`\`
 
-**Output:**
-\`\`\`
-[dry-run] Would pull 3 manifests from cloud
-- app/settings: 1.2 KB (remote newer)
-- app/preferences: 0.8 KB (already in sync)
-- app/theme: 0.5 KB (conflict detected)
-\`\`\`
+Nothing is written. Human lines are prefixed \`[dry-run]\`; under \`--json\`
+the output is still one document, and reported errors or conflicts still
+fail the run.
 
 ## Error Handling
 
-Sync errors are tracked in sync state:
-
-\`\`\`ts
-interface SyncError {
-  manifestId: string;
-  error: 'network' | 'schema' | 'conflict' | 'auth';
-  message: string;
-  retryable: boolean;
-  retryAfter?: number;  // milliseconds
-}
-\`\`\`
+Sync failures are typed \`CapabilityError\` values carrying value-free facts
+(code and reason), never remote bodies or credentials:
 
-**Common errors:**
-- \`network\` — Cloud API unreachable (retryable)
-- \`schema\` — Remote data fails validation (not retryable)
-- \`conflict\` — Both local and remote changed (requires resolution)
-- \`auth\` — Authentication failed (refresh token)
+- \`Remote unreachable\` — connect failure aborts that manifest; never reported as empty remote data
+- \`Schema validation failed\` — only for genuine parse failures, never for connectivity
+- \`conflict\` — both sides diverged; resolve explicitly
+- \`storage-sync-unhealthy\` — status targets reporting error or conflict
+- \`storage-sync-pull-failed\` / \`storage-sync-push-failed\` — the run-level envelope
 
 ## Best Practices
 
 1. **Sync small, focused manifests** — Don't sync entire databases
-2. **Use appropriate conflict resolution** — Match strategy to data semantics
+2. **Use appropriate conflict handling** — Match strategy to data semantics
 3. **Monitor sync state** — Check \`vibes storage sync status\` regularly
 4. **Handle schema migrations** — Version your schemas for backward compatibility
 5. **Test with dry-run** — Always dry-run before production sync
@@ -264,7 +254,7 @@ interface SyncError {
 :::card{title="See also"}
 - [\`storage.adapters\`](storage.adapters) — Adapter implementations
 - [\`storage.manifests\`](storage.manifests) — Manifest declarations
-- [\`config.environment\`](config.environment) — Environment configuration
+- [\`storage.records\`](storage.records) — Record CRUD over manifests
 :::
 `
     },

package/dist/docs/sync.docs.descriptor.js.map

@@ -1 +1 @@
-{"version":3,"file":"sync.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/sync.docs.descriptor.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,GAAwB;IACvC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,cAAc;IAClB,KAAK,EAAE,cAAc;IACrB,OAAO,EAAE,oEAAoE;IAC7E,IAAI,EAAE;QACL,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoQT;KACC;IACD,MAAM,EAAE,SAAS;IACjB,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,UAAU,EAAE,iBAAiB,CAAC;IACrE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC;IAClC,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,OAAO,EAAE,IAAI;CACb,CAAC;AAEF,eAAe,UAAU,CAAC"}
+{"version":3,"file":"sync.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/sync.docs.descriptor.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,GAAwB;IACvC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,cAAc;IAClB,KAAK,EAAE,cAAc;IACrB,OAAO,EAAE,qEAAqE;IAC9E,IAAI,EAAE;QACL,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0PT;KACC;IACD,MAAM,EAAE,SAAS;IACjB,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,UAAU,EAAE,iBAAiB,CAAC;IACrE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC;IAClC,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,OAAO,EAAE,IAAI;CACb,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/transform.docs.descriptor.d.ts

@@ -0,0 +1,4 @@
+import type { DocsTopicDescriptor } from '@vibesdotdev/docs-contracts';
+declare const descriptor: DocsTopicDescriptor;
+export default descriptor;
+//# sourceMappingURL=transform.docs.descriptor.d.ts.map

package/dist/docs/transform.docs.descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transform.docs.descriptor.d.ts","sourceRoot":"","sources":["../../src/docs/transform.docs.descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAEvE,QAAA,MAAM,UAAU,EAAE,mBAmIjB,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/transform.docs.descriptor.js

@@ -0,0 +1,134 @@
+const descriptor = {
+    kind: 'docs/topic',
+    id: 'storage.transform',
+    title: 'Storage Transforms',
+    summary: 'Row ↔ wire-shape descriptor mapping that backs cloud-backed CRUD collections',
+    body: {
+        type: 'markdown',
+        sourceType: 'raw',
+        source: `---
+title: Storage Transforms
+summary: Row ↔ wire-shape descriptor mapping that backs cloud-backed CRUD collections
+tags: [storage, transform, crud, vibesCrudCollection, cloud]
+parent: storage
+order: 5
+surfaces: [cli, web, in-app]
+hardware: [consumer, cloud]
+---
+
+# Storage Transforms
+
+A **storage transform** converts between a storage adapter's native *row* shape
+(e.g. a Drizzle row from \`model_providers\`) and the *wire-shape descriptor* a
+manifest exposes over HTTP (e.g. \`AIProviderDescriptor\`). It is the seam that
+lets one app own a table while other apps consume canonical descriptors, and it
+is what powers cloud-backed CRUD collections via \`vibesCrudCollection\`.
+
+The \`storage/transform\` runtime kind keeps the **descriptor** (id + metadata,
+serializable) separate from the **implementation** (the \`fromRow\` / \`toRow\`
+closures), so descriptors stay data while implementations hold logic.
+
+## When you need one
+
+- You expose a table over \`/api/<resource>\` with \`vibesCrudCollection\` and the
+  stored row shape differs from the descriptor clients should see.
+- You strip, rename, or compute fields between DB and wire (e.g. hide secrets,
+  flatten relations, add a \`kind\` discriminator).
+
+If the row already *is* the wire shape, you don't need a transform — the CRUD
+helpers fall back to identity automatically.
+
+## Declaring a transform
+
+\`createStorageTransform()\` returns a descriptor + runtime-implementation pair.
+Register both from the owning plugin's \`onRegister(runtime)\` (or list the
+descriptor in the plugin and bind the loader there), so the pair lands on the
+runtime the one boot entry, \`bootstrapVibesRuntime\`, composed:
+
+\`\`\`ts
+import { createStorageTransform } from '@vibesdotdev/storage/transform';
+
+const aiProvidersTransform = createStorageTransform<ProviderRow, ProviderDescriptor>({
+  id: 'ai.providers',
+  manifestId: 'ai.providers',
+  fromRow: (row) => ({ id: row.id, kind: 'ai/provider', name: row.name }),
+  toRow: (d) => ({ name: d.name })   // omit for read-only manifests
+});
+
+runtime.registerDescriptor('storage/transform', aiProvidersTransform.descriptor);
+runtime.registerLoader(
+  'storage/transform',
+  aiProvidersTransform.descriptor.id,
+  async () => aiProvidersTransform.implementation
+);
+\`\`\`
+
+\`direction\` is inferred: providing \`toRow\` yields \`'bidirectional'\`, omitting it
+yields \`'read'\`.
+
+## Resolving a transform
+
+Consumers — chiefly \`vibesCrudCollection\` / \`vibesCrudItem\` from
+\`@vibesdotdev/kit/server/crud\` — resolve the live implementation by id:
+
+\`\`\`ts
+import { resolveStorageTransform } from '@vibesdotdev/storage/transform';
+
+const transform = await resolveStorageTransform(runtime, 'ai.providers');
+// null when none registered → caller falls back to identity (row IS the wire shape)
+\`\`\`
+
+## How vibesCrudCollection uses it
+
+\`\`\`ts
+// apps/ai-web/src/routes/api/providers/+server.ts
+const { GET, POST } = vibesCrudCollection({
+  storageDescriptorId: 'ai.providers',
+  list:   { ...quick.auth(), fetch: (e) => db.query.modelProviders.findMany(...) },
+  create: { ...quick.auth(), validation: { body: schema }, insert: (e, ctx) => db.insert(...) }
+});
+export { GET, POST };
+\`\`\`
+
+The helper resolves the \`ai.providers\` transform on first request and applies
+\`fromRow\` to every row before wrapping it in the canonical wire shape:
+\`{ results: TDescriptor[] }\` for list, \`{ result: TDescriptor }\` for get/create/
+update, and \`204\` for delete.
+
+## Cloud-backed records
+
+The same transform id is the bridge across the network. The
+\`@vibesdotdev/storage/adapters/cloud-api\` adapter implements the \`record\` protocol
+(\`CloudAPIStorageRecord\`) — CRUD over the descriptor's REST endpoints — so a
+consumer app can read/write another app's records through \`vibesCrudCollection\`
+while the owning app serves the canonical collection. See
+[\`storage.sync\`](storage.sync) for the ownerApp pattern and
+[\`storage.records\`](storage.records) for the record kind.
+
+## Rules of thumb
+
+1. **Descriptor is data.** Never put \`fromRow\`/\`toRow\` in the descriptor — they
+   live in the runtime implementation.
+2. **Strip secrets in \`fromRow\`.** Anything the descriptor omits never reaches
+   the client.
+3. **Match \`id\` to the manifest id.** \`vibesCrudCollection\`'s
+   \`storageDescriptorId\` resolves the transform by that id.
+4. **No transform is fine.** Identity fallback means a row-shaped API needs no
+   transform at all.
+
+:::card{title="See also"}
+- [\`storage.records\`](storage.records) — the \`storage/record\` kind
+- [\`storage.sync\`](storage.sync) — cross-app sync + ownerApp + cloud-api
+- [\`storage.manifests\`](storage.manifests) — manifest declarations
+:::
+`
+    },
+    parent: 'storage',
+    order: 5,
+    tags: ['storage', 'transform', 'crud', 'vibesCrudCollection', 'cloud'],
+    surfaces: ['cli', 'web', 'in-app'],
+    hardware: ['consumer', 'cloud'],
+    enabled: true
+};
+export default descriptor;
+//# sourceMappingURL=transform.docs.descriptor.js.map

package/dist/docs/transform.docs.descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transform.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/transform.docs.descriptor.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,GAAwB;IACvC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,mBAAmB;IACvB,KAAK,EAAE,oBAAoB;IAC3B,OAAO,EAAE,8EAA8E;IACvF,IAAI,EAAE;QACL,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmHT;KACC;IACD,MAAM,EAAE,SAAS;IACjB,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,SAAS,EAAE,WAAW,EAAE,MAAM,EAAE,qBAAqB,EAAE,OAAO,CAAC;IACtE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC;IAClC,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,OAAO,EAAE,IAAI;CACb,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/host-files.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Storage's consumer-only features (backup, retention, sync state) read and
+ * write host files at absolute paths: the Vibes home, a workspace's `.vibes`,
+ * the backups directory. They reach the host only through the runtime's
+ * `filesystem/adapter` kind (unbound: absolute host paths, never a workspace
+ * binding), whose path mechanics (join, dirname, basename) they use too.
+ * Nothing here holds a host API.
+ */
+import { type RuntimeRef } from '@vibesdotdev/kernel';
+import type { FileSystemAdapterInterface } from '@vibesdotdev/filesystem/interfaces/adapter';
+export type HostFileSystem = FileSystemAdapterInterface;
+/** The host path mechanics: the filesystem adapter's own. */
+export type HostPathOps = Pick<FileSystemAdapterInterface, 'join' | 'dirname' | 'basename' | 'isAbsolute'>;
+/**
+ * The unbound host filesystem adapter of `runtime`. A runtime without the kind
+ * refuses `UNAVAILABLE <reason>`; one without an adapter for its scope refuses
+ * with the filesystem's own `filesystem-adapter-*`.
+ */
+export declare function hostFileSystemOf(runtime: RuntimeRef, reason: string): Promise<HostFileSystem>;
+/** What a path is, read without following a link. */
+export type HostEntryKind = 'file' | 'directory' | 'symlink' | 'special' | 'missing';
+/** One entry of a directory listing, as the adapter reports it. */
+export type HostDirectoryEntry = Awaited<ReturnType<HostFileSystem['list']>>[number];
+/** A path's metadata as the adapter's no-follow `stat` reports it. */
+export type HostEntryStat = Awaited<ReturnType<HostFileSystem['stat']>>;
+/**
+ * `stat` without following a link, or `undefined` when the path is absent.
+ * Only the host's `ENOENT` is absence; any other failure reaches the caller.
+ */
+export declare function hostStat(fs: HostFileSystem, path: string): Promise<HostEntryStat | undefined>;
+/** A file's UTF-8 text, or `undefined` when it is absent; any other failure reaches the caller. */
+export declare function hostReadTextIfPresent(fs: HostFileSystem, path: string): Promise<string | undefined>;
+/** Classify `path` without following a link. */
+export declare function hostEntryKind(fs: HostFileSystem, path: string): Promise<HostEntryKind>;
+//# sourceMappingURL=host-files.d.ts.map

package/dist/host-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-files.d.ts","sourceRoot":"","sources":["../src/host-files.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAwC,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAE5F,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,4CAA4C,CAAC;AAE7F,MAAM,MAAM,cAAc,GAAG,0BAA0B,CAAC;AAExD,6DAA6D;AAC7D,MAAM,MAAM,WAAW,GAAG,IAAI,CAAC,0BAA0B,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,GAAG,YAAY,CAAC,CAAC;AAE3G;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CASnG;AAED,qDAAqD;AACrD,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAErF,mEAAmE;AACnE,MAAM,MAAM,kBAAkB,GAAG,OAAO,CAAC,UAAU,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;AAErF,sEAAsE;AACtE,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC,UAAU,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;AAExE;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,EAAE,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CASnG;AAED,mGAAmG;AACnG,wBAAsB,qBAAqB,CAAC,EAAE,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAUzG;AAED,gDAAgD;AAChD,wBAAsB,aAAa,CAAC,EAAE,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAE5F"}