@inneranimalmedia/agentsam-sdk 2.6.3 → 2.6.4

package/packages/agentsam-errors/src/envelope.js

@@ -166,6 +166,59 @@ export function createErrorEnvelope(input = {}) {
   if (!Number.isInteger(envelope.http_status) || envelope.http_status < 100 || envelope.http_status > 599) envelope.http_status = null;
   if (!Number.isInteger(envelope.grpc_status) || envelope.grpc_status < 0 || envelope.grpc_status > 16) envelope.grpc_status = null;
   envelope.fingerprint = optional(input.fingerprint, 128) || fingerprintError(envelope);
+
+  // Optional recovery dimensions (v1-compatible extras — orthogonal to reason enum)
+  const failureClass = input.failure_class || null;
+  if (failureClass) envelope.failure_class = clean(failureClass);
+  if (input.operation && typeof input.operation === 'object') {
+    envelope.operation = Object.freeze({
+      kind: optional(input.operation.kind, 256),
+      action: optional(input.operation.action, 256),
+      resource_type: optional(input.operation.resource_type, 128),
+      resource_id: optional(input.operation.resource_id, 512),
+      read_only: input.operation.read_only === true,
+      idempotent: input.operation.idempotent === true,
+      side_effect_state: optional(input.operation.side_effect_state, 64) || 'unknown',
+    });
+  }
+  if (input.retry && typeof input.retry === 'object') {
+    envelope.retry = Object.freeze({
+      allowed: input.retry.allowed == null ? retryable : Boolean(input.retry.allowed),
+      strategy: optional(input.retry.strategy, 64) || (retryable ? 'exponential_backoff' : 'none'),
+      retry_after_ms: input.retry.retry_after_ms == null ? envelope.retry_after_ms : Math.max(0, Math.round(Number(input.retry.retry_after_ms) || 0)),
+      max_attempts: Number.isInteger(input.retry.max_attempts) ? input.retry.max_attempts : null,
+      requires_idempotency_key: input.retry.requires_idempotency_key === true,
+    });
+  }
+  if (input.fallback && typeof input.fallback === 'object') {
+    envelope.fallback = Object.freeze({
+      allowed: Boolean(input.fallback.allowed),
+      strategy: optional(input.fallback.strategy, 64),
+      preserve_semantics: input.fallback.preserve_semantics !== false,
+      target: optional(input.fallback.target, 256),
+    });
+  }
+  if (input.notify && typeof input.notify === 'object') {
+    envelope.notify = Object.freeze({
+      user: optional(input.notify.user, 64) || 'immediately',
+      operator: optional(input.notify.operator, 64) || 'never',
+      agent: optional(input.notify.agent, 64) || 'stop',
+    });
+  }
+  if (input.cause && typeof input.cause === 'object') {
+    envelope.cause = input.cause;
+  }
+  if (input.status === 'partial' || input.status === 'success' || input.status === 'failure') {
+    envelope.status = input.status;
+  }
+  if (input.completed != null || input.failed != null) {
+    envelope.partial = Object.freeze({
+      completed: Number(input.completed) || 0,
+      failed: Number(input.failed) || 0,
+      failures: Array.isArray(input.failures) ? input.failures : [],
+    });
+  }
+
   return deepFreeze(envelope);
 }
 

package/packages/agentsam-errors/src/index.js

@@ -5,6 +5,7 @@ export * from './normalize.js';
 export * from './redaction.js';
 export * from './fingerprint.js';
 export * from './retry.js';
+export * from './recovery.js';
 export * from './transport.js';
 export * from './render.js';
 export * from './adapters/index.js';

package/packages/agentsam-errors/src/recovery.js

@@ -0,0 +1,301 @@
+/**
+ * Recovery policy — separates "what failed" from "what to do".
+ *
+ * ErrorEnvelope → planRecovery → RecoveryPlan → SAM executes
+ *
+ * Critical rule: unknown side_effect_state ⇒ reconcile before retry.
+ */
+
+export const FAILURE_CLASS = Object.freeze({
+  INPUT: 'input',
+  AUTHENTICATION: 'authentication',
+  AUTHORIZATION: 'authorization',
+  POLICY: 'policy',
+  DISCOVERY: 'discovery',
+  RESOLUTION: 'resolution',
+  TRANSPORT: 'transport',
+  PROTOCOL: 'protocol',
+  TIMEOUT: 'timeout',
+  RATE_LIMIT: 'rate_limit',
+  CAPACITY: 'capacity',
+  RESOURCE: 'resource',
+  FILESYSTEM: 'filesystem',
+  PERSISTENCE: 'persistence',
+  CONSISTENCY: 'consistency',
+  CONFLICT: 'conflict',
+  DEPENDENCY: 'dependency',
+  PROCESS: 'process',
+  IPC: 'ipc',
+  DATA_INTEGRITY: 'data_integrity',
+  CANCELLED: 'cancelled',
+  UNKNOWN: 'unknown',
+});
+
+export const SIDE_EFFECT_STATE = Object.freeze({
+  NONE: 'none',
+  NOT_STARTED: 'not_started',
+  CONFIRMED_NOT_APPLIED: 'confirmed_not_applied',
+  CONFIRMED_APPLIED: 'confirmed_applied',
+  PARTIALLY_APPLIED: 'partially_applied',
+  UNKNOWN: 'unknown',
+});
+
+export const RECOVERY_SCHEMA = 'agentsam.recovery.v1';
+
+const NO_RETRY_OWNERS = new Set(['policy']);
+const CANCEL_REASONS = new Set([
+  'cancelled_by_user',
+  'cancelled_by_agent',
+  'cancelled_by_policy',
+  'cancelled_by_timeout',
+  'cancelled_by_parent',
+  'cancelled',
+]);
+
+/**
+ * Infer failure_class from reason/code when not supplied.
+ * @param {object} error
+ */
+export function inferFailureClass(error = {}) {
+  const given = error.failure_class;
+  if (given && Object.values(FAILURE_CLASS).includes(given)) return given;
+  const reason = String(error.reason || '');
+  const code = String(error.code || '');
+  if (CANCEL_REASONS.has(reason) || code === 'CANCELLED') return FAILURE_CLASS.CANCELLED;
+  if (/^auth_|unauthenticated|credential/.test(reason) || code === 'UNAUTHENTICATED') return FAILURE_CLASS.AUTHENTICATION;
+  if (/permission|authorization|capability/.test(reason) || code === 'PERMISSION_DENIED') return FAILURE_CLASS.AUTHORIZATION;
+  if (/policy/.test(reason)) return FAILURE_CLASS.POLICY;
+  if (/rate_limit|resource_exhausted|quota|budget/.test(reason) || code === 'RESOURCE_EXHAUSTED') return FAILURE_CLASS.RATE_LIMIT;
+  if (/timeout|deadline/.test(reason) || code === 'DEADLINE_EXCEEDED') return FAILURE_CLASS.TIMEOUT;
+  if (/^fs_|filesystem|path_escape|version_conflict/.test(reason)) return FAILURE_CLASS.FILESYSTEM;
+  if (/^db_|persistence|sqlite|d1/.test(reason)) return FAILURE_CLASS.PERSISTENCE;
+  if (/conflict|etag|precondition|serialization/.test(reason) || code === 'ABORTED') return FAILURE_CLASS.CONFLICT;
+  if (/^pty_|process_|ipc_/.test(reason)) return FAILURE_CLASS.PROCESS;
+  if (/transport|connection|dns|tls|websocket|grpc_unavailable/.test(reason) || code === 'UNAVAILABLE') {
+    return FAILURE_CLASS.TRANSPORT;
+  }
+  if (/corrupt|checksum|integrity|data_loss/.test(reason) || code === 'DATA_LOSS') return FAILURE_CLASS.DATA_INTEGRITY;
+  if (/input_|invalid_argument|malformed/.test(reason) || code === 'INVALID_ARGUMENT') return FAILURE_CLASS.INPUT;
+  return FAILURE_CLASS.UNKNOWN;
+}
+
+/**
+ * Infer side_effect_state for the failed operation.
+ * @param {object} error
+ * @param {object} [operationContext]
+ */
+export function inferSideEffectState(error = {}, operationContext = {}) {
+  const op = error.operation || operationContext.operation || {};
+  if (op.side_effect_state) return op.side_effect_state;
+  if (op.read_only === true || op.side_effect_state === SIDE_EFFECT_STATE.NONE) {
+    return SIDE_EFFECT_STATE.NONE;
+  }
+  if (op.idempotent === true && error.retryable) {
+    return SIDE_EFFECT_STATE.CONFIRMED_NOT_APPLIED;
+  }
+  // Timeouts / connection drops on mutating ops → outcome unknown
+  const reason = String(error.reason || '');
+  const code = String(error.code || '');
+  if (
+    code === 'DEADLINE_EXCEEDED'
+    || /timeout|connection_reset|connection_closed|truncated/.test(reason)
+  ) {
+    if (op.read_only) return SIDE_EFFECT_STATE.NONE;
+    return SIDE_EFFECT_STATE.UNKNOWN;
+  }
+  if (error.retryable === false && /permission|auth|input|policy/.test(reason)) {
+    return SIDE_EFFECT_STATE.CONFIRMED_NOT_APPLIED;
+  }
+  return op.kind ? SIDE_EFFECT_STATE.UNKNOWN : SIDE_EFFECT_STATE.NONE;
+}
+
+/**
+ * Central recovery planner — one policy for CLI / Worker / Studio / MCP.
+ *
+ * @param {object} error  ErrorEnvelope (v1+)
+ * @param {object} [operationContext]
+ * @returns {object} RecoveryPlan
+ */
+export function planRecovery(error = {}, operationContext = {}) {
+  const failure_class = inferFailureClass(error);
+  const side_effect_state = inferSideEffectState(error, operationContext);
+  const attempt = Number(operationContext.attempt || error.retry?.attempt || 1);
+  const maxAttempts = Number(
+    operationContext.max_attempts
+    ?? error.retry?.max_attempts
+    ?? (error.retryable ? 4 : 1),
+  );
+  const evidence = [];
+  evidence.push(`failure_class=${failure_class}`);
+  evidence.push(`side_effect_state=${side_effect_state}`);
+  evidence.push(`reason=${error.reason || 'unknown'}`);
+
+  /** @type {object} */
+  let plan = {
+    schema: RECOVERY_SCHEMA,
+    error_fingerprint: error.fingerprint || null,
+    disposition: 'abort',
+    attempts: { current: attempt, maximum: maxAttempts },
+    delay_ms: null,
+    fallback: null,
+    notify: {
+      user: 'immediately',
+      operator: 'never',
+      agent: 'stop',
+    },
+    reason: error.reason || 'unknown',
+    evidence,
+  };
+
+  // Cancellations are not defects
+  if (failure_class === FAILURE_CLASS.CANCELLED) {
+    return freezePlan({
+      ...plan,
+      disposition: 'abort',
+      notify: { user: 'never', operator: 'never', agent: 'stop' },
+      reason: 'cancelled',
+      evidence: [...evidence, 'cancellation_is_not_a_defect'],
+    });
+  }
+
+  // Ambiguous side effects: NEVER blind retry
+  if (
+    side_effect_state === SIDE_EFFECT_STATE.UNKNOWN
+    || side_effect_state === SIDE_EFFECT_STATE.PARTIALLY_APPLIED
+  ) {
+    return freezePlan({
+      ...plan,
+      disposition: 'reconcile',
+      notify: { user: 'immediately', operator: 'warning', agent: 'wait' },
+      reason: 'side_effect_uncertain',
+      evidence: [...evidence, 'reconcile_before_retry'],
+    });
+  }
+
+  // Policy / auth hard stops
+  if (
+    failure_class === FAILURE_CLASS.POLICY
+    || failure_class === FAILURE_CLASS.AUTHORIZATION
+    || NO_RETRY_OWNERS.has(error.resolution_owner)
+  ) {
+    return freezePlan({
+      ...plan,
+      disposition: 'await_user',
+      notify: { user: 'immediately', operator: 'never', agent: 'wait' },
+      reason: 'policy_or_auth_blocks_retry',
+    });
+  }
+
+  if (failure_class === FAILURE_CLASS.AUTHENTICATION) {
+    return freezePlan({
+      ...plan,
+      disposition: 'await_user',
+      notify: { user: 'immediately', operator: 'never', agent: 'wait' },
+      reason: 'authentication_required',
+    });
+  }
+
+  if (failure_class === FAILURE_CLASS.INPUT || failure_class === FAILURE_CLASS.CONFLICT) {
+    const disposition = failure_class === FAILURE_CLASS.CONFLICT && error.retryable
+      ? 'retry'
+      : 'await_user';
+    return freezePlan({
+      ...plan,
+      disposition,
+      delay_ms: disposition === 'retry' ? 0 : null,
+      attempts: { current: attempt, maximum: Math.min(maxAttempts, 2) },
+      notify: {
+        user: disposition === 'await_user' ? 'immediately' : 'after_retry_exhausted',
+        operator: 'never',
+        agent: disposition === 'retry' ? 'retry' : 'wait',
+      },
+      reason: failure_class === FAILURE_CLASS.CONFLICT ? 'optimistic_concurrency' : 'invalid_input',
+    });
+  }
+
+  // Safe retry path
+  if (error.retryable && attempt < maxAttempts) {
+    const delay = retryDelayFor(error, attempt, failure_class);
+    return freezePlan({
+      ...plan,
+      disposition: failure_class === FAILURE_CLASS.TRANSPORT || /pty_|websocket|connection/.test(String(error.reason))
+        ? 'reconnect'
+        : 'retry',
+      delay_ms: delay,
+      notify: {
+        user: attempt >= 2 ? 'on_degradation' : 'never',
+        operator: 'never',
+        agent: 'retry',
+      },
+      reason: 'retry_budget_remaining',
+      evidence: [...evidence, `delay_ms=${delay}`],
+    });
+  }
+
+  // Fallback if permitted and semantics-preserving
+  const fallbackAllowed = error.fallback?.allowed === true
+    || operationContext.fallback_allowed === true;
+  const preserve = error.fallback?.preserve_semantics !== false
+    && operationContext.preserve_semantics !== false;
+  if (fallbackAllowed && preserve) {
+    return freezePlan({
+      ...plan,
+      disposition: 'fallback',
+      fallback: {
+        kind: error.fallback?.strategy || operationContext.fallback_strategy || 'degraded_mode',
+        target: error.fallback?.target || operationContext.fallback_target || null,
+      },
+      notify: { user: 'on_degradation', operator: 'warning', agent: 'continue' },
+      reason: 'semantic_fallback_allowed',
+    });
+  }
+
+  // Replan if GOAP/A* context available
+  if (operationContext.replan_allowed) {
+    return freezePlan({
+      ...plan,
+      disposition: 'replan',
+      notify: { user: 'on_degradation', operator: 'never', agent: 'replan' },
+      reason: 'retry_exhausted_replan',
+    });
+  }
+
+  // Terminal block
+  return freezePlan({
+    ...plan,
+    disposition: error.resolution_owner === 'user' ? 'await_user' : 'abort',
+    notify: {
+      user: 'immediately',
+      operator: error.severity === 'blocking_internal' ? 'incident' : 'warning',
+      agent: 'stop',
+    },
+    reason: 'recovery_exhausted',
+  });
+}
+
+function retryDelayFor(error, attempt, failureClass) {
+  if (Number.isFinite(error.retry_after_ms) && error.retry_after_ms >= 0) {
+    return Math.round(error.retry_after_ms);
+  }
+  if (failureClass === FAILURE_CLASS.RATE_LIMIT) {
+    return Math.min(60_000, Math.round(1000 * (2 ** Math.min(6, attempt - 1))));
+  }
+  if (failureClass === FAILURE_CLASS.TRANSPORT || failureClass === FAILURE_CLASS.TIMEOUT) {
+    const base = 250;
+    const capped = Math.min(8_000, base * (2 ** Math.min(5, attempt - 1)));
+    const jitter = Math.floor(Math.random() * Math.max(50, capped * 0.2));
+    return capped + jitter;
+  }
+  if (failureClass === FAILURE_CLASS.CONFLICT) return 0;
+  return Math.min(4_000, 500 * (2 ** Math.min(4, attempt - 1)));
+}
+
+function freezePlan(plan) {
+  return Object.freeze({
+    ...plan,
+    attempts: Object.freeze({ ...plan.attempts }),
+    notify: Object.freeze({ ...plan.notify }),
+    fallback: plan.fallback ? Object.freeze({ ...plan.fallback }) : null,
+    evidence: Object.freeze([...(plan.evidence || [])]),
+  });
+}

package/packages/agentsam-knowledge/src/providers/index.js

@@ -6,13 +6,13 @@ const finiteVector = (vector, dimensions) => {
   return vector;
 };
 
-function httpAdapter({ id, env, models, request, credentials = env }) {
+function httpAdapter({ id, env, models, request, credentials = env, allowAnyModel = false }) {
   return Object.freeze({
     id,
     capabilities: () => ({ id, operational: Boolean(credentials()), models, credentials: credentials() ? 'available' : 'missing' }),
     validate(profile) {
       if (clean(profile?.provider) !== id) throw new Error(`provider_profile_mismatch:${id}`);
-      if (!models.includes(clean(profile?.model))) throw new Error(`provider_model_unsupported:${id}:${profile?.model}`);
+      if (!allowAnyModel && !models.includes(clean(profile?.model))) throw new Error(`provider_model_unsupported:${id}:${profile?.model}`);
       if (!Number.isInteger(profile?.dimensions) || profile.dimensions < 1) throw new Error('provider_dimensions_required');
       if (!credentials()) throw new Error(`provider_credentials_unavailable:${id}`);
     },
@@ -70,13 +70,25 @@ export function createWorkersAiProvider({ binding } = {}) {
   });
 }
 
-export function createOllamaProvider({ endpoint = process.env.OLLAMA_HOST || 'http://127.0.0.1:11434', fetchImpl = globalThis.fetch } = {}) {
-  return httpAdapter({ id: 'ollama', env: 'OLLAMA_HOST', models: ['nomic-embed-text', 'mxbai-embed-large'], credentials: () => endpoint,
+export function createOllamaProvider({ endpoint = process.env.OLLAMA_HOST || 'http://127.0.0.1:11434', fetchImpl = globalThis.fetch, models } = {}) {
+  // Model allowlist is advisory only — live `ollama list` / tags are authoritative at selection time.
+  const known = Array.isArray(models) && models.length ? models : ['mxbai-embed-large', 'nomic-embed-text'];
+  return httpAdapter({
+    id: 'ollama',
+    env: 'OLLAMA_HOST',
+    models: known,
+    allowAnyModel: true,
+    credentials: () => endpoint,
     request: async (text, profile) => {
-      const response = await fetchImpl(new URL('/api/embed', endpoint), { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ model: profile.model, input: text }) });
+      const response = await fetchImpl(new URL('/api/embed', endpoint), {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ model: profile.model, input: text }),
+      });
       if (!response.ok) throw new Error(`provider_request_failed:ollama:${response.status}`);
       return finiteVector((await response.json()).embeddings?.[0], profile.dimensions);
-    } });
+    },
+  });
 }
 
 export function createProviderRegistry(options = {}) {

package/packages/connectors/cloudflare/src/routes.js

@@ -220,6 +220,15 @@ export async function handleCloudflareConnectionRequest(request, env) {
       state,
       codeChallenge: challenge,
     });
+    // Browser navigation → 302 to Cloudflare. XHR/fetch (Integrations UI) → JSON.
+    const accept = String(request.headers.get('accept') || '');
+    const mode = String(request.headers.get('sec-fetch-mode') || '');
+    const wantsJson = accept.includes('application/json')
+      || mode === 'cors'
+      || request.headers.get('x-agentsam-oauth') === 'json';
+    if (!wantsJson) {
+      return Response.redirect(authorize, 302);
+    }
     return json({ ok: true, authorize_url: authorize, callback: CLOUDFLARE_CALLBACK_PATH });
   }
 

package/packages/connectors/cloudflare/tests/connector.test.mjs

@@ -64,7 +64,10 @@ describe('cloudflare connector', () => {
     };
     const response = await handleCloudflareConnectionRequest(
       new Request('https://agentsam.example/api/connections/cloudflare/start?return_to=https://untrusted.example/after', {
-        headers: { authorization: 'Bearer fixture' },
+        headers: {
+          authorization: 'Bearer fixture',
+          accept: 'application/json',
+        },
       }),
       {
         DB,
@@ -82,6 +85,28 @@ describe('cloudflare connector', () => {
     assert.equal(stateInsert.args.at(-1), null);
   });
 
+  it('redirects browser starts to Cloudflare authorization', async () => {
+    const oauthState = new Map();
+    const response = await handleCloudflareConnectionRequest(
+      new Request('https://agentsam.example/api/connections/cloudflare/start', {
+        headers: { authorization: 'Bearer fixture' },
+      }),
+      {
+        fixtureSessions: new Map([['fixture', 'user_123']]),
+        oauthState,
+        CLOUDFLARE_OAUTH_CLIENT_ID: 'real-client-id',
+      },
+    );
+
+    assert.equal(response.status, 302);
+    const location = new URL(response.headers.get('location'));
+    assert.equal(location.origin, 'https://dash.cloudflare.com');
+    assert.equal(location.pathname, '/oauth2/auth');
+    assert.equal(location.searchParams.get('client_id'), 'real-client-id');
+    assert.equal(location.searchParams.get('redirect_uri'), 'https://agentsam.example/api/connections/cloudflare/callback');
+    assert.equal(oauthState.size, 1);
+  });
+
   it('consumes callback state and stores only encrypted OAuth tokens', async () => {
     const now = Math.floor(Date.now() / 1000);
     const calls = [];

package/packages/identity/.agentsam/features/oauth-login-portal/agentsam.feature.json

@@ -6,7 +6,7 @@
   "status": "extracted",
   "package": {
     "name": "@inneranimalmedia/agentsam-sdk-identity",
-    "version": "2.6.2",
+    "version": "2.6.3",
     "directory": "packages/identity"
   },
   "provides": [

package/packages/identity/.agentsam/features/oauth-login-portal/routes.json

@@ -46,11 +46,20 @@
       "provider": "github"
     },
     {
-      "path": "/api/oauth/iam/start",
+      "path": "/api/oauth/inneranimalmedia/start",
       "kind": "api",
       "access": "public",
       "provider": "inneranimalmedia",
-      "oauth_provider_key": "iam"
+      "oauth_provider_key": "iam",
+      "aliases": ["/api/oauth/iam/start"]
+    },
+    {
+      "path": "/api/oauth/inneranimalmedia/callback",
+      "kind": "api",
+      "access": "public",
+      "provider": "inneranimalmedia",
+      "oauth_provider_key": "iam",
+      "aliases": ["/api/oauth/iam/callback"]
     },
     {
       "path": "/api/oauth/cloudflare/start",

package/packages/identity/docs/PORTABLE_IDENTITY_ARCHITECTURE.md

@@ -0,0 +1,50 @@
+# Portable Identity Architecture (pre-commit return)
+
+## Invariants
+
+1. Portable SDK owns **semantic route IDs** (`identity.login`), never host paths.
+2. App manifests own **HTTP projections**.
+3. Auth-capable apps MUST declare authenticated / login / recovery / OAuth callback.
+4. OAuth **transactions** persist `app_id` + `return_to` (required).
+5. Post-login: valid `return_to` → authenticated entry → recovery+error → **throw** (never `/`).
+6. No `DASHBOARD_AFTER_LOGIN_PATH`, no `LOCAL_STUDIO_APP` in identity, no `APP_HOME_PATH` env.
+7. Missing shell/route → package verification failure.
+
+## Artifacts delivered
+
+| Deliverable | Location |
+|---|---|
+| IdentityStore + errors | `packages/identity/src/contracts/identity-store.js` |
+| Semantic IDs | `packages/identity/src/contracts/route-ids.js` |
+| Route projection | `packages/identity/src/contracts/route-projection.js` |
+| Fail-closed post-auth | `packages/identity/src/server/post-auth.js` |
+| SESSION_POLICY | `packages/identity/src/core/session-policy.js` |
+| SQLite core pack | `packages/identity/migrations/sqlite/001_identity_core.sql` |
+| SQLite oauth-client | `packages/identity/migrations/sqlite/002_identity_oauth_client.sql` |
+| SQLite oauth-server (optional) | `packages/identity/migrations/sqlite/003_identity_oauth_server.sql` |
+| D1 mapping | `packages/identity/migrations/D1_SCHEMA_MAPPING.md` |
+| createSqliteIdentityAdapter | `packages/identity/src/adapters/sqlite/index.js` |
+| App verify | `packages/identity/src/app/verify-app.js` |
+| App auth contract (Local Studio) | `apps/local-studio/agentsam.app.json` |
+| Tests | `packages/identity/tests/portable-identity-architecture.test.mjs` |
+
+## Redirect resolution
+
+```
+transaction.return_to  →  owned by app?
+        yes → use
+        no  → app.authenticated
+        missing → identity.recovery?error=…
+        none → IdentityRoutingError('AUTH_DESTINATION_UNRESOLVED')
+```
+
+## Local-only path
+
+```
+applySqliteIdentityMigrations(db)  // core + oauth-client
+createSqliteIdentityAdapter(db)
+createIdentityService({ adapter, app, routeRegistry })
+```
+
+Zero Cloudflare / IAM / D1 required for password + session + OAuth transaction store.
+Provider secrets → encrypted vault via `credential_ref` on `identity_provider_connections`.

package/packages/identity/migrations/D1_SCHEMA_MAPPING.md

@@ -0,0 +1,31 @@
+# Identity schema mapping — portable ↔ Cloudflare D1
+
+Portable SQLite (`packages/identity/migrations/sqlite/`) is the product schema.
+The D1 adapter maps existing hosted table names without requiring a big-bang rename.
+
+| Portable (SQLite) | Hosted D1 (current) | Notes |
+|---|---|---|
+| `identity_users` | `auth_users` | Same columns |
+| `identity_external_accounts` | `account_identities` | `user_id` ↔ `account_id` |
+| `identity_sessions` | `auth_sessions` | Same columns |
+| `identity_auth_events` | `auth_event_log` | Same columns |
+| `identity_oauth_transactions` | `identity_oauth_states` → migrate to `identity_oauth_transactions` | Requires `app_id NOT NULL`; no silent pre-app_id fallback |
+| `identity_provider_connections` | (new / connector tables) | `credential_ref` → vault/KMS; never store raw tokens in D1 rows |
+| `identity_app_registry` | cache of `agentsam.app.json` | Disk manifests remain SSOT |
+| `identity_route_registry` | projection cache | Disk manifests remain SSOT |
+| `identity_oauth_clients` … | optional `identity.oauth-server` pack | Only if product is an AS |
+
+## Schema version
+
+Both adapters read `identity_schema_meta.schema_version` (SQLite) or
+`PRAGMA`/meta row. Missing `app_id` on OAuth transactions is an
+`IdentitySchemaError('IDENTITY_SCHEMA_MIGRATION_REQUIRED')`, not a soft
+downgrade.
+
+## Packs
+
+| Pack | Apply when |
+|---|---|
+| `identity.core` | Always (local + hosted) |
+| `identity.oauth-client` | Signing into external IdPs |
+| `identity.oauth-server` | Product issues its own codes/tokens |