@inneranimalmedia/agentsam-sdk 2.5.0 → 2.6.1

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

@@ -0,0 +1,223 @@
+import {
+  CLOUDFLARE_CALLBACK_PATH,
+  CLOUDFLARE_OAUTH_TOKEN_URL,
+  CLOUDFLARE_OAUTH_REVOKE_URL,
+  buildAuthorizeUrl,
+  cloudflareConnectionSafeStatus,
+  resolveCloudflareOAuthClient,
+  requestedCloudflareScopes,
+  assertConnectionOwner,
+} from './index.js';
+import { resolveAuthenticatedOwner } from './owner.js';
+import { sealToken, vaultConfigured } from './vault.js';
+
+function json(data, status = 200) {
+  return new Response(JSON.stringify(data), {
+    status,
+    headers: { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' },
+  });
+}
+
+function redirect(location) {
+  return new Response(null, { status: 302, headers: { location } });
+}
+
+export function isCloudflareConnectionPath(pathname) {
+  return pathname === '/api/connections/cloudflare'
+    || pathname === '/api/connections/cloudflare/start'
+    || pathname === CLOUDFLARE_CALLBACK_PATH
+    || pathname === '/api/connections/cloudflare/disconnect';
+}
+
+async function ensureTables(env) {
+  if (!env?.DB?.prepare) return;
+  await env.DB.prepare(`CREATE TABLE IF NOT EXISTS agentsam_cloudflare_connections (
+    connection_id TEXT PRIMARY KEY,
+    owner_id TEXT NOT NULL,
+    cloudflare_account_id TEXT,
+    scopes TEXT,
+    status TEXT,
+    access_token_encrypted TEXT,
+    refresh_token_encrypted TEXT,
+    created_at INTEGER,
+    updated_at INTEGER,
+    expires_at INTEGER
+  )`).run();
+  await env.DB.prepare(`CREATE TABLE IF NOT EXISTS agentsam_cloudflare_oauth_state (
+    state TEXT PRIMARY KEY,
+    owner_id TEXT NOT NULL,
+    code_verifier TEXT NOT NULL,
+    created_at INTEGER
+  )`).run();
+}
+
+export async function handleCloudflareConnectionRequest(request, env) {
+  const url = new URL(request.url);
+  const client = resolveCloudflareOAuthClient(env);
+  if (request.method === 'OPTIONS') {
+    return new Response(null, { status: 204 });
+  }
+
+  let body = {};
+  if (request.method === 'POST') {
+    body = await request.json().catch(() => ({}));
+  }
+
+  const isCallback = url.pathname === CLOUDFLARE_CALLBACK_PATH && request.method === 'GET';
+  let ownerId = '';
+  try {
+    ownerId = await resolveAuthenticatedOwner(request, env, url, body);
+  } catch (err) {
+    if (!isCallback || err.code === 'untrusted_owner_hint') {
+      const code = err.code || 'unauthenticated';
+      return json({ ok: false, error: code }, code === 'untrusted_owner_hint' ? 400 : 401);
+    }
+  }
+
+  if (!client.productionReady) {
+    if (url.pathname === '/api/connections/cloudflare' && request.method === 'GET') {
+      return json({
+        ok: true,
+        ...cloudflareConnectionSafeStatus(env, null, ownerId),
+      });
+    }
+    if (url.pathname === '/api/connections/cloudflare/start') {
+      return json({
+        ok: false,
+        error: 'not_configured',
+        message: 'real Cloudflare OAuth client still required',
+        fixture: client.fixture,
+      }, 503);
+    }
+  }
+
+  await ensureTables(env);
+
+  if (url.pathname === '/api/connections/cloudflare' && request.method === 'GET') {
+    let connection = null;
+    if (env.DB) {
+      const row = await env.DB.prepare(
+        `SELECT connection_id, owner_id, cloudflare_account_id, scopes, status, created_at, updated_at, expires_at
+         FROM agentsam_cloudflare_connections WHERE owner_id = ? LIMIT 1`,
+      ).bind(ownerId).first();
+      if (row) {
+        connection = {
+          connectionId: row.connection_id,
+          ownerId: row.owner_id,
+          cloudflareAccountId: row.cloudflare_account_id,
+          scopes: row.scopes ? String(row.scopes).split(' ') : [],
+          status: row.status,
+          createdAt: row.created_at,
+          updatedAt: row.updated_at,
+          expiresAt: row.expires_at,
+        };
+      }
+    }
+    return json({ ok: true, ...cloudflareConnectionSafeStatus(env, connection, ownerId) });
+  }
+
+  if (url.pathname === '/api/connections/cloudflare/start' && request.method === 'GET') {
+    const state = crypto.randomUUID().replace(/-/g, '');
+    const verifierBytes = crypto.getRandomValues(new Uint8Array(32));
+    const verifier = btoa(String.fromCharCode(...verifierBytes)).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+    const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier));
+    const challenge = btoa(String.fromCharCode(...new Uint8Array(digest))).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+    if (env.DB) {
+      await env.DB.prepare(
+        `INSERT INTO agentsam_cloudflare_oauth_state (state, owner_id, code_verifier, created_at) VALUES (?, ?, ?, unixepoch())`,
+      ).bind(state, ownerId, verifier).run();
+    } else if (env.oauthState instanceof Map) {
+      env.oauthState.set(state, { ownerId, verifier });
+    }
+    const redirectUri = `${url.origin}${CLOUDFLARE_CALLBACK_PATH}`;
+    const authorize = buildAuthorizeUrl({
+      clientId: String(env.CLOUDFLARE_OAUTH_CLIENT_ID),
+      redirectUri,
+      state,
+      codeChallenge: challenge,
+    });
+    return json({ ok: true, authorize_url: authorize, callback: CLOUDFLARE_CALLBACK_PATH });
+  }
+
+  if (url.pathname === CLOUDFLARE_CALLBACK_PATH && request.method === 'GET') {
+    const code = url.searchParams.get('code') || '';
+    const state = url.searchParams.get('state') || '';
+    let stored = null;
+    if (env.DB) {
+      stored = await env.DB.prepare(
+        `SELECT owner_id, code_verifier FROM agentsam_cloudflare_oauth_state WHERE state = ?`,
+      ).bind(state).first();
+    } else if (env.oauthState instanceof Map) {
+      stored = env.oauthState.get(state);
+      if (stored) stored = { owner_id: stored.ownerId, code_verifier: stored.verifier };
+    }
+    if (!stored) {
+      return json({ ok: false, error: 'cloudflare_connection_forbidden' }, 403);
+    }
+    if (!ownerId) ownerId = stored.owner_id;
+    if (stored.owner_id !== ownerId) {
+      return json({ ok: false, error: 'cloudflare_connection_forbidden' }, 403);
+    }
+    const tokenRes = await fetch(CLOUDFLARE_OAUTH_TOKEN_URL, {
+      method: 'POST',
+      headers: { 'content-type': 'application/x-www-form-urlencoded' },
+      body: new URLSearchParams({
+        grant_type: 'authorization_code',
+        code,
+        redirect_uri: `${url.origin}${CLOUDFLARE_CALLBACK_PATH}`,
+        client_id: String(env.CLOUDFLARE_OAUTH_CLIENT_ID),
+        client_secret: String(env.CLOUDFLARE_OAUTH_CLIENT_SECRET),
+        code_verifier: stored.code_verifier,
+      }),
+    });
+    if (!tokenRes.ok) {
+      return json({ ok: false, error: 'token_exchange_failed' }, 502);
+    }
+    const tokens = await tokenRes.json();
+    const connectionId = `cfconn_${crypto.randomUUID().replace(/-/g, '').slice(0, 16)}`;
+    if (tokens.access_token && !vaultConfigured(env)) {
+      return json({ ok: false, error: 'vault_unavailable' }, 503);
+    }
+    const aad = `cloudflare-connection:${ownerId}`;
+    let accessEnc = null;
+    let refreshEnc = null;
+    try {
+      accessEnc = await sealToken(env, tokens.access_token, aad);
+      refreshEnc = await sealToken(env, tokens.refresh_token, aad);
+    } catch (err) {
+      return json({ ok: false, error: err.code || 'vault_unavailable' }, 503);
+    }
+    if (env.DB) {
+      await env.DB.prepare(
+        `INSERT INTO agentsam_cloudflare_connections (
+           connection_id, owner_id, cloudflare_account_id, scopes, status,
+           access_token_encrypted, refresh_token_encrypted, created_at, updated_at, expires_at
+         ) VALUES (?, ?, ?, ?, 'connected', ?, ?, unixepoch(), unixepoch(), ?)`,
+      ).bind(
+        connectionId,
+        ownerId,
+        tokens.account_id || null,
+        (tokens.scope || requestedCloudflareScopes().join(' ')),
+        accessEnc,
+        refreshEnc,
+        tokens.expires_in ? Math.floor(Date.now() / 1000) + Number(tokens.expires_in) : null,
+      ).run();
+    }
+    return redirect(`/agentsam?connection=cloudflare`);
+  }
+
+  if (url.pathname === '/api/connections/cloudflare/disconnect' && request.method === 'POST') {
+    if (env.DB) {
+      const row = await env.DB.prepare(
+        `SELECT connection_id, owner_id FROM agentsam_cloudflare_connections WHERE owner_id = ?`,
+      ).bind(ownerId).first();
+      if (row) {
+        assertConnectionOwner({ ownerId: row.owner_id, connectionId: row.connection_id }, ownerId);
+        await env.DB.prepare(`DELETE FROM agentsam_cloudflare_connections WHERE owner_id = ?`).bind(ownerId).run();
+      }
+    }
+    return json({ ok: true, status: 'not_configured' });
+  }
+
+  return json({ ok: false, error: 'not_found' }, 404);
+}

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

@@ -0,0 +1,80 @@
+/**
+ * AES-256-GCM token vault matching apps/local-studio/backend/worker encryptSecret.
+ * Connector tokens are server-only. Never return plaintext on status routes.
+ */
+const enc = new TextEncoder();
+const dec = new TextDecoder();
+
+function b64ToBytes(value) {
+  const bin = atob(value);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i += 1) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+function bytesToB64(bytes) {
+  let bin = '';
+  for (const b of bytes) bin += String.fromCharCode(b);
+  return btoa(bin);
+}
+
+export function vaultConfigured(env = {}) {
+  return Boolean(env.VAULT_MASTER_KEY || env.VAULT_KEY);
+}
+
+async function importVaultKey(env) {
+  const raw = env.VAULT_MASTER_KEY || env.VAULT_KEY;
+  if (!raw) throw new Error('VAULT_MASTER_KEY missing');
+  let keyBytes;
+  try {
+    keyBytes = b64ToBytes(raw);
+  } catch {
+    keyBytes = enc.encode(raw);
+  }
+  if (keyBytes.byteLength === 32) {
+    // ok
+  } else if (keyBytes.byteLength > 32) {
+    keyBytes = keyBytes.slice(0, 32);
+  } else {
+    const hash = await crypto.subtle.digest('SHA-256', keyBytes);
+    keyBytes = new Uint8Array(hash);
+  }
+  return crypto.subtle.importKey('raw', keyBytes, { name: 'AES-GCM' }, false, ['encrypt', 'decrypt']);
+}
+
+export async function encryptSecret(env, plaintext, aad) {
+  const key = await importVaultKey(env);
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const cipher = await crypto.subtle.encrypt(
+    { name: 'AES-GCM', iv, additionalData: enc.encode(aad || '') },
+    key,
+    enc.encode(plaintext),
+  );
+  const packed = new Uint8Array(iv.byteLength + cipher.byteLength);
+  packed.set(iv, 0);
+  packed.set(new Uint8Array(cipher), iv.byteLength);
+  return bytesToB64(packed);
+}
+
+export async function decryptSecret(env, packedB64, aad) {
+  const key = await importVaultKey(env);
+  const packed = b64ToBytes(packedB64);
+  const iv = packed.slice(0, 12);
+  const data = packed.slice(12);
+  const plain = await crypto.subtle.decrypt(
+    { name: 'AES-GCM', iv, additionalData: enc.encode(aad || '') },
+    key,
+    data,
+  );
+  return dec.decode(plain);
+}
+
+export async function sealToken(env, plaintext, aad) {
+  if (!plaintext) return null;
+  if (!vaultConfigured(env)) {
+    const err = new Error('vault_unavailable');
+    err.code = 'vault_unavailable';
+    throw err;
+  }
+  return encryptSecret(env, plaintext, aad);
+}

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

@@ -0,0 +1,44 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import {
+  assertConnectionOwner,
+  cloudflareConnectionSafeStatus,
+  resolveCloudflareOAuthClient,
+} from '../src/index.js';
+
+describe('cloudflare connector', () => {
+  it('reports not_configured when credentials are absent', () => {
+    const client = resolveCloudflareOAuthClient({});
+    assert.equal(client.status, 'not_configured');
+    assert.equal(client.configured, false);
+    assert.equal(client.productionReady, false);
+  });
+
+  it('loads fake fixtures without treating them as production authority', () => {
+    const client = resolveCloudflareOAuthClient({
+      CLOUDFLARE_OAUTH_CLIENT_ID: 'sillynotreal',
+      CLOUDFLARE_OAUTH_CLIENT_SECRET: 'sillynotreal-secret',
+    });
+    assert.equal(client.configured, true);
+    assert.equal(client.fixture, true);
+    assert.equal(client.productionReady, false);
+    assert.equal(client.status, 'fixture');
+  });
+
+  it('never includes secrets in safe status output', () => {
+    const status = cloudflareConnectionSafeStatus({
+      CLOUDFLARE_OAUTH_CLIENT_ID: 'sillynotreal',
+      CLOUDFLARE_OAUTH_CLIENT_SECRET: 'sillynotreal-secret',
+    });
+    const blob = JSON.stringify(status);
+    assert.equal(blob.includes('sillynotreal-secret'), false);
+    assert.equal(status.secret, 'configured');
+    assert.equal(status.configured, false);
+  });
+
+  it('denies cross-account connection access', () => {
+    const record = { ownerId: 'sam', connectionId: 'c1' };
+    assert.throws(() => assertConnectionOwner(record, 'connor'), /cloudflare_connection_forbidden/);
+    assert.equal(assertConnectionOwner(record, 'sam').connectionId, 'c1');
+  });
+});

package/packages/identity/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@inneranimalmedia/agentsam-sdk-identity",
-  "version": "2.5.0",
+  "version": "2.6.1",
   "private": true,
   "type": "module",
-  "description": "Identity module for @inneranimalmedia/agentsam-sdk (workspace \u2014 publish via root SDK)",
+  "description": "Identity module for @inneranimalmedia/agentsam-sdk (workspace — publish via root SDK)",
   "agentsam": {
     "system": "identity",
     "kind": "library",

package/packages/identity/src/contracts/auth-config.js

@@ -5,20 +5,24 @@
  * may provide storage/verification adapters without inventing competing aliases.
  *
  * Canonical variables:
- *   IAM_ORIGIN            IAM authority + browser/OAuth/API origin
+ *   IAM_OAUTH_ISSUER      public authorization-server authority (issuer)
  *   IAM_CLIENT_ID         OAuth client id
  *   IAM_CLIENT_SECRET     OAuth client secret
+ *   IAM_ORIGIN            deprecated alias of IAM_OAUTH_ISSUER (migration window)
  *   AGENTSAM_SDK_KEY      account/delegated sdk_* bearer
  *   AGENTSAM_BRIDGE_KEY   machine/integration credential
  *
  * Migration-only fallbacks:
- *   IAM_OAUTH_ISSUER      -> IAM_ORIGIN
+ *   IAM_ORIGIN            -> IAM_OAUTH_ISSUER
  *   AGENTSAM_SDK_TOKEN    -> AGENTSAM_SDK_KEY
  */
 
-export const DEFAULT_IAM_ORIGIN = 'https://inneranimalmedia.com';
+export const DEFAULT_IAM_OAUTH_ISSUER = 'https://inneranimalmedia.com';
+/** @deprecated Use DEFAULT_IAM_OAUTH_ISSUER. */
+export const DEFAULT_IAM_ORIGIN = DEFAULT_IAM_OAUTH_ISSUER;
 
 export const AGENTSAM_AUTH_ENV = Object.freeze({
+  iamIssuer: 'IAM_OAUTH_ISSUER',
   iamOrigin: 'IAM_ORIGIN',
   iamClientId: 'IAM_CLIENT_ID',
   iamClientSecret: 'IAM_CLIENT_SECRET',
@@ -27,7 +31,7 @@ export const AGENTSAM_AUTH_ENV = Object.freeze({
 });
 
 export const AGENTSAM_AUTH_LEGACY_ENV = Object.freeze({
-  iamOrigin: 'IAM_OAUTH_ISSUER',
+  iamOrigin: 'IAM_ORIGIN',
   sdkKey: 'AGENTSAM_SDK_TOKEN',
 });
 
@@ -35,6 +39,7 @@ export const AGENTSAM_AUTH_CONTRACT = Object.freeze({
   version: 1,
   authority: 'agentsam-sdk',
   iam: Object.freeze({
+    issuer: AGENTSAM_AUTH_ENV.iamIssuer,
     origin: AGENTSAM_AUTH_ENV.iamOrigin,
     clientId: AGENTSAM_AUTH_ENV.iamClientId,
     clientSecret: AGENTSAM_AUTH_ENV.iamClientSecret,
@@ -54,6 +59,7 @@ export const AGENTSAM_AUTH_CONTRACT = Object.freeze({
   }),
   compatibility: Object.freeze({
     iamOriginFallback: AGENTSAM_AUTH_LEGACY_ENV.iamOrigin,
+    iamIssuerCanonical: AGENTSAM_AUTH_ENV.iamIssuer,
     sdkKeyFallback: AGENTSAM_AUTH_LEGACY_ENV.sdkKey,
   }),
 });
@@ -66,13 +72,18 @@ function normalizeOrigin(value) {
   return clean(value).replace(/\/+$/, '');
 }
 
-/** Resolve canonical IAM authority origin with one migration fallback. */
-export function resolveIamOrigin(env = {}, explicit = '') {
+/** Resolve canonical IAM issuer. IAM_OAUTH_ISSUER wins; IAM_ORIGIN is compatibility only. */
+export function resolveIamIssuer(env = {}, explicit = '') {
   return normalizeOrigin(
-    explicit || env?.IAM_ORIGIN || env?.IAM_OAUTH_ISSUER || DEFAULT_IAM_ORIGIN,
+    explicit || env?.IAM_OAUTH_ISSUER || env?.IAM_ORIGIN || DEFAULT_IAM_OAUTH_ISSUER,
   );
 }
 
+/** @deprecated Use resolveIamIssuer. Same resolution order as issuer. */
+export function resolveIamOrigin(env = {}, explicit = '') {
+  return resolveIamIssuer(env, explicit);
+}
+
 /** Resolve account/delegated SDK bearer; canonical name wins over legacy. */
 export function resolveSdkKey(env = {}, explicit = '') {
   return clean(explicit || env?.AGENTSAM_SDK_KEY || env?.AGENTSAM_SDK_TOKEN);

package/packages/identity/tests/auth-config.test.mjs

@@ -9,23 +9,27 @@ import {
 } from '../src/contracts/auth-config.js';
 
 describe('auth configuration contract', () => {
-  it('prefers canonical IAM_ORIGIN over the migration alias', () => {
+  it('prefers canonical IAM_OAUTH_ISSUER over IAM_ORIGIN', () => {
     assert.equal(
       resolveIamOrigin({
-        IAM_ORIGIN: 'https://canonical.example.test/',
-        IAM_OAUTH_ISSUER: 'https://legacy.example.test/',
+        IAM_ORIGIN: 'https://legacy.example.test/',
+        IAM_OAUTH_ISSUER: 'https://canonical.example.test/',
       }),
       'https://canonical.example.test',
     );
   });
 
-  it('accepts IAM_OAUTH_ISSUER as migration-only fallback', () => {
+  it('accepts IAM_ORIGIN as migration-only fallback', () => {
     assert.equal(
-      resolveIamOrigin({ IAM_OAUTH_ISSUER: 'https://legacy.example.test/' }),
+      resolveIamOrigin({ IAM_ORIGIN: 'https://legacy.example.test/' }),
       'https://legacy.example.test',
     );
   });
 
+  it('defaults issuer when neither IAM_OAUTH_ISSUER nor IAM_ORIGIN exists', () => {
+    assert.equal(resolveIamOrigin({}), 'https://inneranimalmedia.com');
+  });
+
   it('prefers AGENTSAM_SDK_KEY over AGENTSAM_SDK_TOKEN', () => {
     assert.equal(
       resolveSdkKey({

package/packages/identity/tests/oauth-credentials.test.mjs

@@ -46,18 +46,18 @@ describe('oauth credentials', () => {
     assert.equal(resolveOAuthCredentialLane(env, 'iam')?.lane, 'iam_platform');
   });
 
-  it('prefers IAM_ORIGIN and exposes origin as the canonical authority', () => {
+  it('prefers IAM_OAUTH_ISSUER and exposes issuer as the canonical authority', () => {
     const creds = resolveIamPlatformCredentials({
       IAM_CLIENT_ID: 'c',
       IAM_CLIENT_SECRET: 's',
-      IAM_ORIGIN: 'https://iam.example.test/',
-      IAM_OAUTH_ISSUER: 'https://legacy.example.test/',
+      IAM_ORIGIN: 'https://legacy.example.test/',
+      IAM_OAUTH_ISSUER: 'https://iam.example.test/',
     });
     assert.equal(creds?.origin, 'https://iam.example.test');
     assert.equal(creds?.issuer, 'https://iam.example.test');
   });
 
-  it('accepts IAM_OAUTH_ISSUER only as a migration fallback', () => {
+  it('accepts IAM_ORIGIN only as a migration fallback', () => {
     const creds = resolveIamPlatformCredentials({
       IAM_CLIENT_ID: 'c',
       IAM_CLIENT_SECRET: 's',

package/protocol/COMPANY_REPOSITORY_GRAPH_V1.md

@@ -0,0 +1,91 @@
+# AgentSam Company Repository Graph v1
+
+This protocol defines the portable vocabulary for company-wide repository identity, public contracts, dependency edges, and Merkle evidence. It does not make the SDK a global database.
+
+## Authority split
+
+- `agentsam-sdk` defines schemas, enums, builders, Merkle formats, and receipt semantics.
+- The authenticated host owns `account_id` and persists the operational graph.
+- `code_repositories` is the canonical repository registry.
+- `agentsam_repository_contracts` records what a repository provides.
+- `agentsam_repository_dependencies` records what a repository consumes and the policy attached to that edge.
+- `agentsam_fs_merkle_snapshots` indexes exact repository states; full manifests may live in object storage.
+- Deployment and deployment-health tables record whether a source state reached production and whether it remains healthy.
+- MCP may expose graph queries; ExecOS may emit execution evidence. Neither becomes the ownership authority.
+
+## Ownership law
+
+Persisted company graph records use `account_id` as ownership SSOT. `tenant_id`, `workspace_id`, `user_id`, and `owner_user_id` are not part of this protocol.
+
+Portable repository identity is deliberately different: a checked-in repository identity must not embed an account identifier. The host binds its stable `repository_id` to an authenticated `account_id` in the registry.
+
+## Canonical repository identity
+
+A Git remote is evidence, not authority. The SDK must not derive the canonical `repository_id` from `owner/repo`, a checkout path, a workspace, or a provider URL. Persistence callers provide the `repository_id` from the host registry.
+
+## Graph levels
+
+```text
+code_repositories
+  repository identity / company role
+        |
+        +-- agentsam_repository_contracts
+        |     what this repository provides
+        |
+        +-- agentsam_repository_dependencies
+              what this repository consumes
+                    |
+                    +-- Merkle / AST / Git evidence
+                    |
+                    +-- deployments / deployment health
+```
+
+`codebase_dep_edges` remains an intra-repository code graph. `agentsam_repository_dependencies` is a cross-repository company graph. They are not interchangeable.
+
+## Contract records
+
+Contract types are:
+
+`api | schema | runtime | cli | event | receipt | package`
+
+Statuses are:
+
+`active | deprecated | retired`
+
+A contract record carries a stable `contract_key`, explicit version, manifest path when one exists, and `contract_hash`. The hash is the semantic identity consumers can pin independently of a Git branch name.
+
+## Dependency records
+
+Dependency types are:
+
+`runtime | build | contract | package | deploy | tool | data`
+
+Criticality is:
+
+`informational | compatible | strict | critical`
+
+Failure policy is:
+
+`warn | block_certification | block_deploy | degrade`
+
+The dependency graph supplies the meaning a Merkle tree cannot infer by itself: who consumes a changed contract and what should happen if the requirement is violated.
+
+## Merkle persistence v2
+
+Company persistence uses:
+
+```text
+account_id + repository_id + snapshot_id
+```
+
+Object keys are:
+
+```text
+agentsam_fs_merkle_snapshots/<account_id>/<repository_id>/<snapshot_id>.json
+```
+
+The content root, metadata root, and policy hash remain separate authorities. A future contract/dependency aggregate root may be layered above these records without changing the content Merkle format.
+
+## Certification
+
+Version 1 intentionally does not require a separate certifications table. A host can derive an initial certification decision from repository identity, contract hashes, dependency requirements, Merkle roots, verification results, deployments, and deployment health. A persistent certification ledger can be added when there is a real need to preserve compatibility statements across an exact set of repository roots.

package/protocol/MERKLE_PERSISTENCE_V1.md

@@ -1,5 +1,7 @@
 # AgentSam Merkle Persistence v1
 
+> Superseded for current company persistence by `MERKLE_PERSISTENCE_V2.md`. V1 is retained only as the historical contract shipped before the account/repository hard cut.
+
 Persistence is a host concern layered on top of the portable Merkle protocol. The SDK exposes the canonical table name, storage prefix, logical asset binding, storage-key helper, and portable SQL schema without owning a customer's database or cloud credentials.
 
 ## Authority split

package/protocol/MERKLE_PERSISTENCE_V2.md

@@ -0,0 +1,40 @@
+# AgentSam Merkle Persistence v2
+
+Persistence is a host concern layered on top of the portable Merkle protocol. Version 2 hard-cuts persisted ownership to `account_id + repository_id` and removes user/workspace/tenant ownership aliases.
+
+## Authority split
+
+```text
+root_hash       = filesystem/content authority
+metadata_root   = semantic/index authority
+policy_hash     = capture-scope authority
+account_id      = authenticated ownership authority
+repository_id   = canonical repository-registry identity
+```
+
+A checkout path, workspace, or user identity must never become `repository_id`. For registered Git repositories, the SDK may derive the canonical provider identity directly from the Git remote (for example `github:owner/repo`), matching the `code_repositories.id` convention; local repositories may fall back to the committed project manifest.
+
+The optional searchable index table remains `agentsam_fs_merkle_snapshots`. Full manifests may be stored under the provider-neutral object prefix `agentsam_fs_merkle_snapshots/`.
+
+Typical keys are:
+
+```text
+agentsam_fs_merkle_snapshots/<account_id>/<repository_id>/<snapshot_id>.json
+```
+
+The hosting application chooses physical storage and database bindings. The SDK never owns cloud credentials and never invents account or repository authority.
+
+## CLI publication
+
+```sh
+agentsam login
+agentsam merkle snapshot . --semantic --out .agentsam/merkle.json
+agentsam merkle persist .agentsam/merkle.json \
+  --wrangler-config path/to/wrangler.toml \
+  --capture-kind deploy \
+  --deployment-id "$DEPLOYMENT_ID"
+```
+
+The CLI reads `account_id` from the authenticated local AgentSam session and resolves `repository_id` from Git/provider identity, with the committed project manifest as fallback for local repositories. Programmatic hosts still pass authenticated `account_id + repository_id` directly to `buildMerklePersistencePlan`. For non-deploy captures, execution provenance remains required through a connection or runtime lease. `--dry-run` emits the exact storage/index plan without writes; `--r2-only` uploads the manifest without a D1 index write.
+
+Version 1 used `owner_user_id` / `repo_id` and is superseded for current company persistence.

package/protocol/README.md

@@ -12,6 +12,7 @@ Platform repositories may consume the SDK, provide host adapters, or incubate pr
 4. **Contracts travel with the SDK.** Shared schemas and protocol definitions live under `protocol/` and are versioned with the code that consumes them.
 5. **No copied package trees.** Do not duplicate `protocol/`, `agentsam_sdk/`, or package source under another path in this repository or another repository merely to keep two homes in sync.
 6. **Repository tools observe before they prescribe.** Generic repository intelligence must accept an explicit repo root, be read-only by default, and must not hardcode one repository's folder names, tenant IDs, workspace IDs, providers, or framework layout.
+7. **Model facts have one authority chain.** `/models`, CLI JSON, runtime selection, and usage receipts must follow the normative model SSOT contract in `protocol/models/README.md`; provider facts retain authoritative provenance while AgentSam recommendations remain separate policy.
 
 ## Layout
 

package/protocol/capabilities/cloudflare-cpu-audit-input.schema.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.inneranimalmedia.com/agentsam/capabilities/cloudflare-cpu-audit-input.schema.json",
+  "title": "cloudflare.cpu.audit input",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["file"],
+  "properties": {
+    "cwd": { "type": "string", "minLength": 1 },
+    "file": { "type": "string", "minLength": 1 },
+    "sources": {
+      "type": "array",
+      "maxItems": 12,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "maxFrames": { "type": "integer", "minimum": 1, "maximum": 100 },
+    "maxSourceChars": { "type": "integer", "minimum": 1000, "maximum": 64000, "default": 24000 }
+  }
+}