@inneranimalmedia/agentsam-sdk 2.4.1 → 2.6.0

package/packages/identity/src/index.js

@@ -43,6 +43,7 @@ export {
 export * from './core/index.js';
 export * from './core/constants.js';
 export { DEFAULT_COMPANY_ID, DEFAULT_COMPANY_SLUG, normalizeCompanyRow } from './contracts/company.js';
+export * from './contracts/auth-config.js';
 export { createPasswordResetService } from './recovery/password-reset.js';
 export {
   finalizeInboundOAuth,

package/packages/identity/src/oauth/README.md

@@ -6,7 +6,7 @@
 | Developer Google | `GOOGLE_CLIENT_ID` + `GOOGLE_CLIENT_SECRET` | Takes `/api/oauth/google/start` when set |
 | Developer GitHub | `GITHUB_CLIENT_ID` + `GITHUB_CLIENT_SECRET` | Takes `/api/oauth/github/start` when set |
 
-Optional: `IAM_OAUTH_ISSUER` (default `https://inneranimalmedia.com`).
+Optional: `IAM_ORIGIN` (default `https://inneranimalmedia.com`).
 
 ## Secrets law
 
@@ -30,7 +30,7 @@ Register IAM redirect URI: `https://<customer-host>/api/oauth/iam/callback`
 
 ## IAM authorization server endpoints (issuer)
 
-The customer worker redirects users to the **issuer** (`IAM_OAUTH_ISSUER`, default production IAM):
+The customer worker redirects users to the **issuer** (`IAM_ORIGIN`, default production IAM):
 
 | Step | Endpoint |
 |------|----------|

package/packages/identity/src/oauth/credentials.js

@@ -1,3 +1,5 @@
+import { DEFAULT_IAM_ORIGIN, resolveIamOrigin } from '../contracts/auth-config.js';
+
 /**
  * OAuth credential lanes for customer apps.
  *
@@ -9,20 +11,22 @@
  * take the /api/oauth/{provider}/start button; otherwise the button uses IAM.
  */
 
-export const DEFAULT_IAM_OAUTH_ISSUER = 'https://inneranimalmedia.com';
+/** @deprecated Use DEFAULT_IAM_ORIGIN from the auth configuration contract. */
+export const DEFAULT_IAM_OAUTH_ISSUER = DEFAULT_IAM_ORIGIN;
 export const IAM_PLATFORM_STATE_PROVIDER = 'iam_platform';
 export const IAM_PLATFORM_CALLBACK_PATH = '/api/oauth/iam/callback';
 
 /**
  * @param {Record<string, unknown> | null | undefined} env
- * @returns {{ clientId: string, clientSecret: string, issuer: string } | null}
+ * @returns {{ clientId: string, clientSecret: string, origin: string, issuer: string } | null}
  */
 export function resolveIamPlatformCredentials(env) {
   const clientId = String(env?.IAM_CLIENT_ID || '').trim();
   const clientSecret = String(env?.IAM_CLIENT_SECRET || '').trim();
   if (!clientId || !clientSecret) return null;
-  const issuer = String(env?.IAM_OAUTH_ISSUER || DEFAULT_IAM_OAUTH_ISSUER).replace(/\/+$/, '');
-  return { clientId, clientSecret, issuer };
+  const origin = resolveIamOrigin(env);
+  // `issuer` remains for one migration window so existing consumers do not break.
+  return { clientId, clientSecret, origin, issuer: origin };
 }
 
 /** @param {Record<string, unknown> | null | undefined} env */
@@ -43,6 +47,7 @@ export function requireIamPlatformCredentials(env) {
  *   lane: 'iam_platform' | 'byok_google' | 'byok_github',
  *   clientId: string,
  *   clientSecret: string,
+ *   origin?: string,
  *   issuer?: string,
  *   provider: string,
  * } | null}
@@ -55,6 +60,7 @@ export function resolveOAuthCredentialLane(env, provider) {
       lane: 'iam_platform',
       clientId: iam.clientId,
       clientSecret: iam.clientSecret,
+      origin: iam.origin,
       issuer: iam.issuer,
       provider: 'iam',
     };
@@ -83,6 +89,7 @@ export function resolveOAuthCredentialLane(env, provider) {
       lane: 'iam_platform',
       clientId: iam.clientId,
       clientSecret: iam.clientSecret,
+      origin: iam.origin,
       issuer: iam.issuer,
       provider,
     };

package/packages/identity/src/oauth/iam-platform.js

@@ -42,7 +42,7 @@ export async function iamPlatformOAuthStart(request, env, adapter) {
 
   const redirectUri = `${url.origin}${IAM_PLATFORM_CALLBACK_PATH}`;
   const authUrl = getIamAuthUrl({
-    issuer: creds.issuer,
+    origin: creds.origin,
     clientId: creds.clientId,
     redirectUri,
     state,
@@ -80,7 +80,7 @@ export async function iamPlatformOAuthCallback(request, env, adapter, identity)
 
   const redirectUri = `${url.origin}${IAM_PLATFORM_CALLBACK_PATH}`;
   const token = await exchangeIamCode({
-    issuer: creds.issuer,
+    origin: creds.origin,
     clientId: creds.clientId,
     clientSecret: creds.clientSecret,
     code,
@@ -92,7 +92,7 @@ export async function iamPlatformOAuthCallback(request, env, adapter, identity)
   }
 
   const profile = await fetchIamProfile({
-    issuer: creds.issuer,
+    origin: creds.origin,
     accessToken: token.access_token,
   });
   const normalized = profile ? normalizeIamIdentity(profile) : null;

package/packages/identity/src/providers/iam/index.js

@@ -9,18 +9,18 @@ import {
 } from './oauth.js';
 import { fetchIamProfile } from './profile.js';
 import { normalizeIamIdentity } from './mapper.js';
-import { DEFAULT_IAM_OAUTH_ISSUER } from '../../oauth/credentials.js';
+import { DEFAULT_IAM_ORIGIN } from '../../contracts/auth-config.js';
 
 /**
- * @param {string} [issuer]
+ * @param {string} [origin]
  */
-export function createIamIdentityProvider(issuer = DEFAULT_IAM_OAUTH_ISSUER) {
-  const resolvedIssuer = String(issuer || DEFAULT_IAM_OAUTH_ISSUER).replace(/\/+$/, '');
+export function createIamIdentityProvider(origin = DEFAULT_IAM_ORIGIN) {
+  const resolvedOrigin = String(origin || DEFAULT_IAM_ORIGIN).replace(/\/+$/, '');
   return createIdentityProvider({
     id: 'iam',
-    authorizeUrl: (input) => getIamAuthUrl({ ...input, issuer: resolvedIssuer }),
-    exchangeCode: (input) => exchangeIamCode({ ...input, issuer: resolvedIssuer }),
-    getProfile: (accessToken) => fetchIamProfile({ issuer: resolvedIssuer, accessToken }),
+    authorizeUrl: (input) => getIamAuthUrl({ ...input, origin: resolvedOrigin }),
+    exchangeCode: (input) => exchangeIamCode({ ...input, origin: resolvedOrigin }),
+    getProfile: (accessToken) => fetchIamProfile({ origin: resolvedOrigin, accessToken }),
     normalizeIdentity: normalizeIamIdentity,
   });
 }

package/packages/identity/src/providers/iam/oauth.js

@@ -3,14 +3,15 @@ export const IAM_IDENTITY_TOKEN_PATH = '/api/oauth/identity/token';
 export const IAM_IDENTITY_USERINFO_PATH = '/api/oauth/identity/userinfo';
 export const IAM_DEFAULT_OIDC_SCOPE = 'openid profile email';
 
-function normalizeIssuer(issuer) {
-  return String(issuer || '').replace(/\/+$/, '');
+function normalizeOrigin(origin, issuer) {
+  return String(origin || issuer || '').replace(/\/+$/, '');
 }
 
 /**
  * @param {import('../../provider-contract.js').OAuthAuthorizeInput & { issuer: string }} input
  */
 export function getIamAuthUrl({
+  origin,
   issuer,
   clientId,
   redirectUri,
@@ -18,7 +19,7 @@ export function getIamAuthUrl({
   codeChallenge,
   scope,
 } = {}) {
-  const base = normalizeIssuer(issuer);
+  const base = normalizeOrigin(origin, issuer);
   const url = new URL(`${base}${IAM_IDENTITY_AUTHORIZE_PATH}`);
   url.searchParams.set('client_id', clientId || '');
   url.searchParams.set('redirect_uri', redirectUri || '');
@@ -36,6 +37,7 @@ export function getIamAuthUrl({
  * @param {import('../../provider-contract.js').OAuthExchangeInput & { issuer: string }} input
  */
 export async function exchangeIamCode({
+  origin,
   issuer,
   code,
   codeVerifier,
@@ -44,7 +46,7 @@ export async function exchangeIamCode({
   redirectUri,
 }) {
   try {
-    const base = normalizeIssuer(issuer);
+    const base = normalizeOrigin(origin, issuer);
     const body = new URLSearchParams();
     body.set('grant_type', 'authorization_code');
     body.set('code', code || '');

package/packages/identity/src/providers/iam/profile.js

@@ -1,15 +1,15 @@
 import { IAM_IDENTITY_USERINFO_PATH } from './oauth.js';
 
-function normalizeIssuer(issuer) {
-  return String(issuer || '').replace(/\/+$/, '');
+function normalizeOrigin(origin, issuer) {
+  return String(origin || issuer || '').replace(/\/+$/, '');
 }
 
 /**
- * @param {{ issuer: string, accessToken: string }} input
+ * @param {{ origin?: string, issuer?: string, accessToken: string }} input
  */
-export async function fetchIamProfile({ issuer, accessToken }) {
+export async function fetchIamProfile({ origin, issuer, accessToken }) {
   try {
-    const base = normalizeIssuer(issuer);
+    const base = normalizeOrigin(origin, issuer);
     const res = await fetch(`${base}${IAM_IDENTITY_USERINFO_PATH}`, {
       headers: { Authorization: `Bearer ${accessToken}` },
     });

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

@@ -0,0 +1,61 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import {
+  AGENTSAM_AUTH_CONTRACT,
+  buildSdkAuthorizationHeaders,
+  resolveBridgeKey,
+  resolveIamOrigin,
+  resolveSdkKey,
+} from '../src/contracts/auth-config.js';
+
+describe('auth configuration contract', () => {
+  it('prefers canonical IAM_OAUTH_ISSUER over IAM_ORIGIN', () => {
+    assert.equal(
+      resolveIamOrigin({
+        IAM_ORIGIN: 'https://legacy.example.test/',
+        IAM_OAUTH_ISSUER: 'https://canonical.example.test/',
+      }),
+      'https://canonical.example.test',
+    );
+  });
+
+  it('accepts IAM_ORIGIN as migration-only fallback', () => {
+    assert.equal(
+      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({
+        AGENTSAM_SDK_KEY: 'sdk_new',
+        AGENTSAM_SDK_TOKEN: 'sdk_old',
+      }),
+      'sdk_new',
+    );
+    assert.equal(resolveSdkKey({ AGENTSAM_SDK_TOKEN: 'sdk_old' }), 'sdk_old');
+  });
+
+  it('never aliases bridge machine trust to a user SDK key', () => {
+    assert.equal(
+      resolveBridgeKey({ AGENTSAM_BRIDGE_KEY: 'bridge_machine', AGENTSAM_SDK_KEY: 'sdk_user' }),
+      'bridge_machine',
+    );
+    assert.equal(resolveBridgeKey({ AGENTSAM_SDK_KEY: 'sdk_user' }), '');
+    assert.equal(AGENTSAM_AUTH_CONTRACT.bridge.userAuth, false);
+    assert.equal(AGENTSAM_AUTH_CONTRACT.bridge.sdkTokenType, 'integration');
+  });
+
+  it('builds Bearer authorization only for sdk_ keys', () => {
+    assert.deepEqual(buildSdkAuthorizationHeaders('sdk_abc', { Accept: 'application/json' }), {
+      Accept: 'application/json',
+      Authorization: 'Bearer sdk_abc',
+    });
+    assert.throws(() => buildSdkAuthorizationHeaders('bridge_machine'), /AGENTSAM_SDK_KEY_required/);
+  });
+});

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

@@ -46,12 +46,23 @@ describe('oauth credentials', () => {
     assert.equal(resolveOAuthCredentialLane(env, 'iam')?.lane, 'iam_platform');
   });
 
-  it('honors IAM_OAUTH_ISSUER override', () => {
+  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://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_ORIGIN only as a migration fallback', () => {
     const creds = resolveIamPlatformCredentials({
       IAM_CLIENT_ID: 'c',
       IAM_CLIENT_SECRET: 's',
       IAM_OAUTH_ISSUER: 'https://staging.inneranimalmedia.com/',
     });
-    assert.equal(creds?.issuer, 'https://staging.inneranimalmedia.com');
+    assert.equal(creds?.origin, 'https://staging.inneranimalmedia.com');
   });
 });

package/protocol/FILEMETA_V1.md

@@ -0,0 +1,95 @@
+# AgentSam file metadata format, version 1
+
+`agentsam-filemeta` is a deterministic semantic companion to the content-only `agentsam-merkle` protocol. It does **not** replace or extend the content Merkle root. A repository can therefore have the same `merkle_root` and a different `metadata_root` when permissions, classification rules, package metadata, or parser metadata change without changing file bytes or relative paths.
+
+## Envelope
+
+```json
+{
+  "format": "agentsam-filemeta",
+  "version": 1,
+  "algorithm": "sha256",
+  "classifier": {
+    "format": "agentsam-filemeta",
+    "version": 1,
+    "source": "path+package+ast+execution-boundary",
+    "trust_boundary": "execution-domain-v1",
+    "ast_parser": "typescript",
+    "ast_parser_version": "5.9.3"
+  },
+  "rootHash": "sha256:...",
+  "stats": {},
+  "entries": []
+}
+```
+
+`rootHash` is SHA-256 over the canonical semantic envelope payload using the domain prefix `agentsam-filemeta:root:v1\0`. Object keys are recursively sorted; entry order is sorted by unsigned UTF-8 bytes of `path`. The hashed payload contains `classifier` plus the full semantic `entries` array. Summary `stats` are intentionally outside the metadata root.
+
+## File records
+
+Semantic entries correspond one-for-one with non-directory content entries and retain their content linkage:
+
+```json
+{
+  "path": "packages/identity/src/core/accounts.js",
+  "type": "file",
+  "size": 213,
+  "mode": 420,
+  "hash": "sha256:...",
+  "package": "@inneranimalmedia/agentsam-sdk-identity",
+  "package_root": "packages/identity",
+  "package_kind": "library",
+  "system": "identity",
+  "category": "accounts",
+  "layer": "core",
+  "kind": "source",
+  "language": "javascript",
+  "role": "business-logic",
+  "execution_domain": "unknown",
+  "tags": ["account-scoped", "authentication"],
+  "symbols": ["accountLinkingNotConfigured"],
+  "imports": [],
+  "resolved_imports": [],
+  "env_accesses": [],
+  "ast": {
+    "indexed": true,
+    "parser": "typescript",
+    "symbol_count": 1,
+    "dependency_count": 0,
+    "env_access_count": 0,
+    "parse_error_count": 0
+  }
+}
+```
+
+`hash` is the content Merkle entry hash and `size` must match the linked content entry. `mode` is the observed Unix permission bits in decimal. Semantic metadata is derived by convention from repository/package paths, nearest `package.json` metadata, and syntax parsing. JavaScript/TypeScript-family source files up to the implementation size limit receive AST symbol/import metadata, local import-resolution evidence, and environment-variable access names. Values are never read or stored. `execution_domain` classifies observed code as `browser`, `server`, `shared`, `test`, `tooling`, `framework`, or `unknown`; the trust-boundary analyzer consumes these Merkle-bound facts rather than treating directory names as security authority.
+
+## Package overrides
+
+A package may declare stable package-level semantics without tagging every file:
+
+```json
+{
+  "name": "@inneranimalmedia/agentsam-sdk-identity",
+  "agentsam": {
+    "system": "identity",
+    "kind": "library",
+    "tags": ["authentication", "account-scoped"],
+    "classify": [
+      { "glob": "src/core/**", "role": "business-logic" },
+      { "glob": "src/lib/db.ts", "execution_domain": "server", "tags": ["server-only"] }
+    ]
+  }
+}
+```
+
+Convention remains the default. `agentsam.classify` is an optional deterministic override layer for exceptional package layouts such as framework-owned server-function bridges or server-only modules that physically live beneath a frontend package. Overrides are themselves hashed into the metadata root through the resulting semantic entries/classifier contract; they do not weaken the client/server rule.
+
+## Identity boundary
+
+The two roots answer different questions:
+
+- `agentsam-merkle` `rootHash`: did included relative names, file bytes, or literal symlink targets change?
+- `agentsam-filemeta` `rootHash`: did the semantic/index view of those content entries change?
+
+A classifier or parser upgrade may change only the metadata root. A permission-only change may change only the metadata root. A file-byte change normally changes both.

package/protocol/INSPECT_VIEWS_V1.md

@@ -0,0 +1,40 @@
+# AgentSam Inspect Views v1
+
+`repository.snapshot` remains the canonical deterministic repository evidence envelope. Its three independent repository identities remain unchanged:
+
+- `tree.merkle_root` — content identity (paths, bytes, symlink targets)
+- `tree.manifest.policy_hash` — capture-scope identity
+- `tree.metadata_root` — `agentsam-filemeta/v1` semantic metadata identity
+
+Inspect views are **derived projections**, not new repository identities. A projection carries the canonical `snapshot_id`, `content_hash`, and three roots unchanged and adds a separate `projection.projection_hash` for the bounded view itself.
+
+## Agent routing flow
+
+Start with a small facet index instead of injecting every file record. The CLI defaults to this bounded index view; `--view full` is explicit:
+
+```sh
+agentsam inspect --cwd . --json
+agentsam inspect --cwd . --view full --json   # persistence/verification only
+```
+
+For repeated agent turns, capture the canonical snapshot once and reuse it. This avoids repeating Merkle + AST + repository-intelligence work while preserving the exact same canonical identities:
+
+```sh
+agentsam inspect --cwd . --save-snapshot /tmp/repository.snapshot.json --json
+agentsam inspect --cwd . --snapshot-file /tmp/repository.snapshot.json \
+  --view files --system identity --tag authentication --limit 40 --json
+```
+
+Then request only the likely feature surface:
+
+```sh
+agentsam inspect --cwd . --view files --system identity --tag authentication --limit 40 --json
+agentsam inspect --cwd . --view files --system cms-frontend --category cms-editor --json
+agentsam inspect --cwd . --view files --path 'packages/agentsam-workbench/**' --match terminal --json
+```
+
+Supported selectors are `system`, `package`, `category`, `layer`, `kind`, `language`, `role`, `tag`, `path`, `symbol`, `import`, and `match`. Different selector classes are ANDed; repeated values within one selector class are alternatives. `--match` terms are all required and are tested against routing metadata, paths, tags, symbols, and imports.
+
+`--view files` returns compact routing records and never changes `metadata_root`. Use `--view full` when a persistence or verification lane genuinely needs the full canonical evidence envelope.
+
+Machine JSON is compact by default. `--pretty` is presentation-only and never changes any repository identity.

package/protocol/MERKLE_PERSISTENCE_V1.md

@@ -0,0 +1,50 @@
+# AgentSam Merkle Persistence v1
+
+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
+
+```text
+root_hash       = filesystem/content authority
+metadata_root   = semantic/index authority
+policy_hash     = capture-scope authority
+```
+
+None replaces another.
+
+The canonical optional index table is `agentsam_fs_merkle_snapshots`. Full snapshot documents are stored beneath the provider-neutral prefix `agentsam_fs_merkle_snapshots/`.
+
+For Cloudflare presets the logical R2 role is `WEBSITE_ASSETS`. The generated/hosting application decides which physical bucket is bound to that role. A customer may therefore bind their own bucket without changing SDK code:
+
+```toml
+[[r2_buckets]]
+binding = "WEBSITE_ASSETS"
+bucket_name = "customer-selected-bucket"
+```
+
+A host with dynamic or non-Cloudflare storage may inject its own storage adapter instead. The SDK must not infer user identity, account authority, bucket credentials, or deployment identity.
+
+Typical keys are:
+
+```text
+agentsam_fs_merkle_snapshots/<owner>/<repo>/<snapshot>.json
+```
+
+`storage_bucket` records the actual physical destination selected by the host; `storage_key` records the object key. D1/SQLite is the searchable index, not the blob store.
+
+## CLI publication
+
+Create the semantic snapshot once, then publish that exact file through the host's logical bindings:
+
+```sh
+agentsam merkle snapshot . --semantic --out .agentsam/merkle.json
+agentsam merkle persist .agentsam/merkle.json \
+  --wrangler-config path/to/wrangler.toml \
+  --owner-user-id "$AGENTSAM_OWNER_USER_ID" \
+  --capture-kind deploy \
+  --deployment-id "$DEPLOYMENT_ID"
+```
+
+`agentsam merkle persist` resolves `WEBSITE_ASSETS` and `DB` from the selected Wrangler config. It never hard-codes a customer's bucket or database and never invents `owner_user_id`. `--dry-run` emits the resolved R2 key and D1 row without writes; `--r2-only` is available when the host intentionally does not maintain the index table.
+
+The canonical `agentsam-sdk` Worker binds `WEBSITE_ASSETS` to `agentsam-os-blueprint-content` for the SDK's own development/deployment snapshots. That physical name is an installation choice, not part of the portable protocol; generated/customer Workers should bind `WEBSITE_ASSETS` to their selected bucket while retaining the `agentsam_fs_merkle_snapshots/` object namespace.

package/protocol/MERKLE_V1.md

@@ -14,7 +14,9 @@ A directory payload is `[[name,type,hash],...]`, sorted by unsigned UTF-8 bytes
 
 Empty non-root directories and ignored entries are omitted. The root is always a directory node, whose path is the empty string. Node paths use `/` between components, are unique, and cannot contain absolute paths, `.`/`..` segments, NUL, backslashes, or drive prefixes. Filenames/targets must round-trip through UTF-8.
 
-A manifest contains `format: "agentsam-merkle"`, `version: 1`, `algorithm: "sha256"`, `rootPath`, `createdAt`, `policy: {include, exclude}`, `rootHash`, `stats`, and a sorted `entries` array. File entries add byte `size`; symlink entries add `target`. Absolute root paths, timestamps, file sizes, and summary stats are metadata outside the root digest. Content hash and size are both recomputed when scanning; loading recomputes summary stats and validates parent relationships and directory hashes. Snapshot loading does not re-read file contents.
+A manifest contains `format: "agentsam-merkle"`, `version: 1`, `algorithm: "sha256"`, `rootPath`, `createdAt`, `policy: {include, exclude}`, `policyHash`, `rootHash`, `stats`, and a sorted `entries` array. File entries add byte `size`; symlink entries add `target`. Entries may also carry decimal Unix permission bits as `mode` (for example `420` = octal `0644`). `mode` is observational metadata and is **not** included in file, symlink, directory, or root digests, so permission-only changes do not change `rootHash`. Older v1 manifests without `mode` or `policyHash` remain valid; loaders deterministically recompute `policyHash` from the normalized policy. Absolute root paths, timestamps, file sizes, modes, and summary stats are metadata outside the root digest. Content hash and size are both recomputed when scanning; loading recomputes summary stats and validates parent relationships and directory hashes. Snapshot loading does not re-read file contents.
+
+A v1 manifest may also contain an optional `semantic` envelope whose identity is separately defined by `agentsam-filemeta`; it is never an input to `rootHash`. See [FILEMETA_V1](./FILEMETA_V1.md).
 
 The ignore defaults are fixed for version 1 as documented in docs/MERKLE.md. Consumers must compare equivalent policies; an excluded file is outside the integrity claim. A manifest is not signed. Validation checks structure and hash consistency, not baseline authorship. Different line endings or relative names produce different roots even if editors display equivalent text.
 

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 }
+  }
+}

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

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.inneranimalmedia.com/agentsam/capabilities/cloudflare-cpu-profile-input.schema.json",
+  "title": "cloudflare.cpu.profile input",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["file"],
+  "properties": {
+    "cwd": { "type": "string", "minLength": 1 },
+    "file": { "type": "string", "minLength": 1 },
+    "maxFrames": { "type": "integer", "minimum": 1, "maximum": 100 }
+  }
+}

package/protocol/capabilities/cloudflare-wrangler-native-input.schema.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.inneranimalmedia.com/agentsam/capabilities/cloudflare-wrangler-native-input.schema.json",
+  "title": "cloudflare.wrangler.native input",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["command"],
+  "properties": {
+    "command": { "enum": ["whoami", "deployments.list", "versions.list", "types.check", "queues.list"] },
+    "cwd": { "type": "string", "minLength": 1 },
+    "name": { "type": "string" },
+    "account": { "type": "string" },
+    "config": { "type": "string" },
+    "env": { "type": "string" },
+    "profile": { "type": "string" },
+    "path": { "type": "string" },
+    "page": { "type": "integer", "minimum": 1 }
+  }
+}