settld 0.1.1 → 0.1.5

package/docs/pilot-kit/rfp-clause.md

@@ -0,0 +1,46 @@
+# Draft RFP clause (evidence-backed invoices)
+
+This clause is intended to be copy/pasted and then tuned to your policy (strict vs amber, evidence types, SLA/acceptance criteria, etc.).
+
+## Verifiable invoice artifacts
+
+Vendor MUST provide an evidence-backed invoice artifact for each billing period that is independently verifiable without access to vendor systems.
+
+The artifact MUST be one of:
+
+- `InvoiceBundle.v1` (invoice claim + metering + pricing terms + evidence references), or
+- `ClosePack.v1` (invoice claim + metering + pricing terms + evidence references + optional SLA/acceptance evaluation surfaces).
+
+The artifact MUST:
+
+- be an archived bundle (ZIP or directory) containing payload evidence and protocol metadata
+- include a manifest committing (via hashes) to the file set (excluding verifier outputs to avoid circular hashing)
+- include attestations and signatures binding verification receipts to the manifest hash and bundle head attestation hash
+- include buyer-signed pricing terms (e.g. `PricingMatrixSignatures.v2` referencing a canonical pricing matrix hash)
+- support strict verification under explicit buyer-supplied governance trust anchors (provided out-of-band)
+
+## Payment eligibility
+
+Buyer MAY require that an invoice is eligible for payment only when:
+
+- verification is **strict** and **passes** with **no errors**, and
+- warnings (Amber) are either:
+  - disallowed (auto-hold), or
+  - allowed only under an explicit buyer policy, with manual review/audit trail.
+
+## Deliverables and auditability
+
+Vendor MUST provide, per invoice:
+
+- the bundle ZIP bytes (for archiving)
+- deterministic verifier output (`VerifyCliOutput.v1`) and any embedded producer receipt (when present)
+
+Vendor SHOULD provide:
+
+- a hosted view-only verification link for buyer review
+- an “audit packet” export (bundle ZIP + hosted verification JSON + receipt surfaces + non-normative summary PDF + decision record, where applicable)
+
+## Key lifecycle / rotation
+
+Buyer MUST be able to rotate vendor ingest keys without downtime.
+

package/docs/pilot-kit/roi-calculator-template.csv

@@ -0,0 +1,2 @@
+date,tenantId,invoiceId,bundleSha256,mode,ok,verificationOk,warningsCount,errorsCount,disputeAvoided,notes
+

package/docs/pilot-kit/security-qa.md

@@ -0,0 +1,153 @@
+# Verify Cloud (Magic Link) — Security Q&A (pilot)
+
+This document is designed to be pasted into common procurement/security portals with minimal edits.
+
+If you need a single attachment, download the **Security & Controls packet** — it includes this Q&A, an architecture one-pager, a data inventory, and checksums.
+
+## Product summary (what is Verify Cloud?)
+
+Verify Cloud accepts a vendor-submitted **Settld bundle** (typically `InvoiceBundle.v1` or `ClosePack.v1`), verifies it deterministically, and exposes:
+
+- a read-only hosted report page (Green/Amber/Red)
+- deterministic machine-readable outputs (`VerifyCliOutput.v1`)
+- export bundles for audit (audit packet, support bundle)
+
+## Data handling
+
+### What is uploaded?
+
+- A ZIP containing a Settld bundle directory (evidence + protocol metadata + manifest + attestations).
+
+### What is stored?
+
+Storage is filesystem-backed under `MAGIC_LINK_DATA_DIR` (often a PVC mount). Per run, Verify Cloud stores:
+
+- **Bundle ZIP bytes (optional)**: `zips/<token>.zip` (controlled by `TenantSettings.v2.artifactStorage.storeBundleZip`)
+- **Hosted verification output** (`VerifyCliOutput.v1`): `verify/<token>.json`
+- **Redacted public summary** (what feeds hosted UI / exports): `public/<token>.json`
+- **Non-normative PDF summary (optional)** (redacted): `pdf/<token>.pdf` (when invoice claim is present; controlled by `TenantSettings.v2.artifactStorage.storePdf`)
+- **Producer receipt** (when present inside the bundle): `receipt/<token>.json`
+- **ClosePack evaluation/index surfaces** (when present): `closepack/<token>/...`
+- **Webhook delivery records** (optional, no secrets): `webhooks/{attempts,record}/<token>_*.json`
+- **Minimal immutable run record** (metadata-only, for support/accounting): `runs/<tenant>/<token>.json`
+
+Verify Cloud does **not** separately parse and persist raw evidence file contents outside of the uploaded bundle ZIP bytes (other than the allowlisted, redacted “render model” fields used for UI/PDF/CSV/support exports).
+
+### Retention (defaults + enforcement)
+
+- Default retention: `TenantSettings.v2.retentionDays` (default `30` days).
+- Optional per-vendor / per-contract overrides: `TenantSettings.v2.vendorPolicies[*].retentionDays`, `TenantSettings.v2.contractPolicies[*].retentionDays`.
+- Enforcement:
+  - a background maintenance sweeper deletes retained artifacts (default daily), and
+  - uploads opportunistically trigger a sweep before quota checks.
+
+After retention, heavy artifacts (bundle ZIP, verify JSON, PDFs, cached exports, webhook records) are deleted and downloads return `410 retained`. The metadata-only run record remains for support/accounting.
+
+## Security controls
+
+### Authentication models
+
+- **Admin API access**: `x-api-key` header (set `MAGIC_LINK_API_KEY`).
+- **Vendor ingest**: vendor-scoped ingest keys (`Authorization: Bearer <ingestKey>`) with upload-only capability.
+- **Buyer access (optional)**: email OTP login restricted to allowlisted domains (`TenantSettings.v2.buyerAuthEmailDomains`) and per-email roles (`TenantSettings.v2.buyerUserRoles`).
+- **Decision capture (optional)**: approve/hold can be gated by OTP (`TenantSettings.v2.decisionAuthEmailDomains`).
+
+### RBAC roles (buyer)
+
+- `viewer`: view inbox and exports
+- `approver`: export CSV/audit packet, approve/hold
+- `admin`: settings, onboarding packs, support bundle, security packet
+
+### Audit logging
+
+Verify Cloud appends JSONL audit records for:
+
+- tenant settings changes
+- ingest key creation/revocation
+- buyer login events (when enabled)
+- settlement decision capture (approve/hold)
+
+Exports:
+
+- Security & Controls packet (monthly)
+- Audit packet (monthly; deterministic)
+- Optional archival export sink (S3-compatible): push monthly audit packet ZIP + CSV (tenant-configurable)
+- Support bundle (time-bounded; redacted settings + metadata-first)
+
+### Token security (hosted report links)
+
+- Token format: `ml_` + 24 random bytes (192-bit entropy).
+- Token TTL: configurable via `MAGIC_LINK_TOKEN_TTL_SECONDS` (default 7 days).
+- Tokens are revocable via the admin API.
+
+### Rate limiting and budgets
+
+Verify Cloud enforces:
+
+- upload size bound (`MAGIC_LINK_MAX_UPLOAD_BYTES`, default 50 MiB)
+- tenant + IP rate limiting (`TenantSettings.v2.rateLimits.*`; default `uploadsPerHour=100`, `verificationViewsPerHour=1000`)
+- verification timeout (`MAGIC_LINK_VERIFY_TIMEOUT_MS`, default 60s)
+- concurrency caps (`MAGIC_LINK_MAX_CONCURRENT_JOBS`, `MAGIC_LINK_MAX_CONCURRENT_JOBS_PER_TENANT`)
+- queued verify workers with retries + dead-letter accounting (`MAGIC_LINK_VERIFY_QUEUE_*`)
+- hostile ZIP extraction budgets (entry count, path length, per-file bytes, total bytes, compression ratio)
+
+### Secrets handling
+
+- Tenant settings secrets (webhook secret, delegated signer bearer token, etc.) are encrypted at rest when `MAGIC_LINK_SETTINGS_KEY_HEX` is configured (AES-256-GCM).
+- Support exports redact secrets by default (e.g. webhook secret material is removed).
+
+## Threat model (short)
+
+Verify Cloud is designed to resist:
+
+- hostile ZIP attacks (zip-slip traversal, symlinks, duplicates/overwrite, encrypted entries, zip bombs)
+- resource exhaustion (huge uploads, decompression bombs, long-running verification)
+- HTML injection / XSS in rendered fields
+- token guessing / link leakage
+
+Mitigations are summarized in the exported **Security & Controls packet** along with the exact budgets/defaults in effect for that deployment.
+
+## Cryptography / verification integrity
+
+- Bundles are verifiable offline: download the bundle ZIP and run `settld-verify` under buyer-controlled trust anchors.
+- Trust anchors are supplied out-of-band by the buyer (governance roots, pricing signer keys). Hosted verification can run in `strict` or `compat` depending on trust configuration/policy.
+- Cryptographic primitives: SHA-256 hashes and Ed25519 signatures; canonical JSON is used where required for stable hashing.
+
+## Infrastructure expectations
+
+- Verify Cloud is intended to run behind TLS termination (ingress/load balancer). The service itself is HTTP-only by default.
+- Encryption at rest is provided by your underlying storage layer (PVC/disk + cloud/KMS configuration).
+
+## Compliance posture
+
+- Verify Cloud is not currently SOC 2 audited.
+- It is designed with controls that map well to SOC 2 expectations (authn/authz, audit logging, retention enforcement, secure defaults, and exportability for audit).
+
+## Incident response / vulnerability reporting
+
+- Security issues / vulnerability reports: email `aiden@settld.work` (private disclosure).
+- Operational support: see `docs/SUPPORT.md` and `docs/ONCALL_PLAYBOOK.md`.
+
+## Configuration knobs (most commonly requested)
+
+- Environment:
+  - `MAGIC_LINK_API_KEY` — admin access
+  - `MAGIC_LINK_SETTINGS_KEY_HEX` — encrypt secrets at rest (tenant settings)
+  - `MAGIC_LINK_DATA_DIR` — storage location (mount point)
+  - `MAGIC_LINK_TOKEN_TTL_SECONDS` — report link TTL
+  - `MAGIC_LINK_MAX_UPLOAD_BYTES` — upload cap
+  - `MAGIC_LINK_VERIFY_TIMEOUT_MS` — verification timeout
+  - `MAGIC_LINK_RATE_LIMIT_UPLOADS_PER_HOUR` — default per-tenant upload limit (overrideable per tenant)
+  - `MAGIC_LINK_MAX_CONCURRENT_JOBS`, `MAGIC_LINK_MAX_CONCURRENT_JOBS_PER_TENANT` — concurrency caps
+  - `MAGIC_LINK_VERIFY_QUEUE_WORKERS`, `MAGIC_LINK_VERIFY_QUEUE_MAX_ATTEMPTS`, `MAGIC_LINK_VERIFY_QUEUE_RETRY_BACKOFF_MS` — verify queue worker behavior
+  - `MAGIC_LINK_RUN_STORE_MODE`, `MAGIC_LINK_RUN_STORE_DATABASE_URL` — run metadata control-plane store mode (`fs|dual|db`)
+  - `MAGIC_LINK_MAINTENANCE_INTERVAL_SECONDS` — retention sweep interval (maintenance runner)
+- Tenant settings (API):
+  - `retentionDays`, `vendorPolicies[*].retentionDays`, `contractPolicies[*].retentionDays`
+  - `artifactStorage.storeBundleZip`, `artifactStorage.storePdf`, `artifactStorage.precomputeMonthlyAuditPackets`
+  - `archiveExportSink` (S3 archival export sink)
+  - `rateLimits` (per-tenant/per-IP windows for upload/view/decision/OTP endpoints)
+  - `buyerNotifications` (buyer recipient + delivery mode settings)
+  - `buyerAuthEmailDomains`, `buyerUserRoles`
+  - `decisionAuthEmailDomains`
+  - `webhooks[*]` (with secrets encrypted-at-rest when settings key is configured)

package/docs/pilot-kit/security-summary.md

@@ -0,0 +1,35 @@
+# Security summary (Verify Cloud / Magic Link)
+
+This is a short, operator-facing security posture summary for pilots.
+
+## Hostile ZIP ingestion
+
+Magic Link ingestion uses a single safe unzip implementation:
+
+- rejects absolute paths and traversal (`..`) after normalization
+- rejects backslashes and drive letters (`:`)
+- rejects duplicate entries
+- rejects encrypted entries
+- rejects symlinks via external attributes
+- enforces budgets:
+  - max entry count
+  - max per-file bytes
+  - max total uncompressed bytes
+  - max path length
+  - max compression ratio (zip bombs)
+- extracts into a fresh temp dir and never overwrites existing files
+
+## Deterministic outputs (CI / audit friendly)
+
+- Verification output is deterministic JSON (`VerifyCliOutput.v1`) and is intended to be archived.
+- Audit packet ZIP is deterministic and bundles:
+  - bundle ZIP
+  - hosted verify JSON
+  - embedded producer receipt (if present)
+  - PDF summary (non-normative)
+  - decision record (if present)
+
+## Multi-implementation parity
+
+The repo includes a Python reference verifier and a conformance pack; parity is tested in CI.
+

package/docs/plans/2026-02-13-mcp-spike-design.md

@@ -0,0 +1,113 @@
+# MCP Stdio Spike (Sprint 23) Design
+
+Date: 2026-02-13
+
+Owner: Platform
+
+Tickets: `STLD-T2305`, `STLD-T2306`
+
+## Goal
+
+Prove that an MCP-compatible agent can reliably discover and invoke a *curated* set of Settld tools over `stdio`, using a **restricted API key** (not an ops token).
+
+This is a spike: correctness and minimal compatibility matter more than feature breadth. Production hardening (SSE transport, rate limiting, etc.) is explicitly deferred to Sprint 25.
+
+## Non-Goals (S23)
+
+- No SSE transport.
+- No multi-tenant discovery. Tenant is configured via env.
+- No generic “HTTP proxy tool”. We expose curated tools only.
+- No persistence inside the MCP server. It is a stateless bridge to the Settld API.
+
+## Transport + Protocol
+
+- Transport: `stdio`
+- Protocol: JSON-RPC 2.0 message stream.
+- Framing: newline-delimited JSON; additionally accepts `Content-Length:` framed messages for compatibility.
+- Required methods:
+  - `initialize`
+  - `tools/list`
+  - `tools/call`
+- Optional methods (implemented as no-ops / trivial):
+  - `ping`
+  - `notifications/initialized` (ignored)
+
+## Auth Model
+
+- The MCP server requires `SETTLD_API_KEY` and uses `x-proxy-api-key` for all API calls.
+- The API key must have the minimum scopes needed for:
+  - registering agents
+  - marketplace RFQ/bid/accept
+  - wallet credit (requires `x-settld-protocol` header)
+  - agent run event appends (requires `x-settld-protocol` + `x-proxy-expected-prev-chain-hash`)
+  - run dispute transitions (requires `x-settld-protocol`)
+
+No ops token handling is included in the spike.
+
+## Configuration
+
+Environment variables:
+
+- `SETTLD_BASE_URL` (default: `http://127.0.0.1:3000`)
+- `SETTLD_TENANT_ID` (default: `tenant_default`)
+- `SETTLD_API_KEY` (required)
+- `SETTLD_PROTOCOL` (optional; if unset the server attempts to discover via `GET /healthz` response header `x-settld-protocol`, falling back to `1.0`)
+
+## Tool Surface (Curated)
+
+### `settld.create_agreement`
+
+Creates a real marketplace-backed agreement by executing:
+
+1. `POST /agents/register` (payer)
+2. `POST /agents/register` (payee)
+3. `POST /agents/{payerAgentId}/wallet/credit` (fund payer)
+4. `POST /marketplace/rfqs`
+5. `POST /marketplace/rfqs/{rfqId}/bids`
+6. `POST /marketplace/rfqs/{rfqId}/accept` (returns `runId`, agreement, settlement)
+
+Returns IDs needed for subsequent tools: `payerAgentId`, `payeeAgentId`, `rfqId`, `bidId`, `runId`, `settlementId`, `agreementId`.
+
+### `settld.submit_evidence`
+
+Appends an agent run event:
+
+- `GET /agents/{agentId}/runs/{runId}/events` to obtain current `prevChainHash`
+- `POST /agents/{agentId}/runs/{runId}/events` with `type=EVIDENCE_ADDED` and `x-proxy-expected-prev-chain-hash`
+
+### `settld.settle_run`
+
+Moves a run to terminal state (which triggers auto-resolution in the Settld API):
+
+- `GET /agents/{agentId}/runs/{runId}/events` (prevChainHash)
+- `POST /agents/{agentId}/runs/{runId}/events` with `type=RUN_COMPLETED` (or `RUN_FAILED`)
+
+### `settld.open_dispute`
+
+Opens a dispute for a resolved run settlement:
+
+- `POST /runs/{runId}/dispute/open`
+
+## Error Handling
+
+- API errors are surfaced as tool results with `isError=true` and a text payload containing `{ statusCode, message, details }` when available.
+- JSON-RPC protocol errors use standard JSON-RPC error responses.
+
+## Latency Measurement
+
+Each tool call returns `durationMs` measured inside the MCP process (wall-clock). This measures bridge overhead + API time; it is sufficient for spike validation and can be compared against direct API calls later.
+
+## Testing
+
+- A `node --test` smoke test exercises:
+  - `initialize`
+  - `tools/list` (tool names + schemas)
+  - one `tools/call` against a local stub HTTP server (no secrets required)
+
+## Roll Forward Path (S25)
+
+- Add SSE transport.
+- Add richer auth modes (service tokens, per-tool scopes, per-tenant selection).
+- Add stronger redaction of tool outputs.
+- Add structured telemetry and rate limiting.
+

package/docs/spec/AcceptanceCriteria.v1.md

@@ -0,0 +1,17 @@
+# AcceptanceCriteria.v1
+
+`AcceptanceCriteria.v1` defines buyer-side acceptance rules that can be evaluated deterministically and offline from a JobProof-derived job stream.
+
+In ClosePack bundles, it is stored at `acceptance/acceptance_criteria.json`.
+
+## Criteria kinds (v1)
+
+Each criterion has:
+
+- `criterionId` — stable identifier (string).
+- `kind` — one of:
+  - `PROOF_STATUS_EQUALS`
+  - `SLA_OVERALL_OK`
+
+Criteria are evaluated from embedded JobProof facts and (optionally) an `SlaEvaluation.v1`.
+

package/docs/spec/AcceptanceEvaluation.v1.md

@@ -0,0 +1,10 @@
+# AcceptanceEvaluation.v1
+
+`AcceptanceEvaluation.v1` is a deterministic evaluation of `AcceptanceCriteria.v1` against a specific JobProof instance.
+
+In ClosePack bundles, it is stored at `acceptance/acceptance_evaluation.json`.
+
+## Determinism contract
+
+If `acceptance/*` surfaces are present, verifiers recompute the evaluation and require exact match (canonical JSON) in strict mode.
+

package/docs/spec/AgentEvent.v1.md

@@ -0,0 +1,47 @@
+# AgentEvent.v1
+
+`AgentEvent.v1` defines the append-only run event envelope for autonomous agent execution traces.
+
+Each event is scoped to one run stream (`streamId = runId`) and can be used to reconstruct `AgentRun.v1`.
+
+## Schema
+
+See `schemas/AgentEvent.v1.schema.json`.
+
+## Required fields
+
+- `schemaVersion` (const: `AgentEvent.v1`)
+- `v` (event version, const `1`)
+- `id`
+- `streamId` (run ID)
+- `type`
+- `at` (ISO date-time)
+- `actor` (`type` + `id`)
+- `payload`
+
+## Allowed event types (v1)
+
+- `RUN_CREATED`
+- `RUN_STARTED`
+- `RUN_HEARTBEAT`
+- `EVIDENCE_ADDED`
+- `RUN_COMPLETED`
+- `RUN_FAILED`
+
+## Signature and chain fields
+
+The following fields are optional in `AgentEvent.v1` but reserved for signed chain envelopes:
+
+- `payloadHash`
+- `prevChainHash`
+- `chainHash`
+- `signature`
+- `signerKeyId`
+
+If present, these fields must be verifiable using the same hash/signature model used by Settld chained events.
+
+## Determinism
+
+Event application order is stream order.
+
+When multiple events share the same timestamp, ordering is defined by append order in the stored run stream.

package/docs/spec/AgentIdentity.v1.md

@@ -0,0 +1,62 @@
+# AgentIdentity.v1
+
+`AgentIdentity.v1` defines a portable, tenant-scoped identity record for autonomous agents.
+
+This object is intended to be:
+
+- deterministic (stable field names + required core fields),
+- cryptographically bound (primary verification key is explicit), and
+- reusable across API, SDK, and future trust/reputation surfaces.
+
+## Schema
+
+See `schemas/AgentIdentity.v1.schema.json`.
+
+## Canonicalization and hashing
+
+When `AgentIdentity.v1` is signed or hashed by higher-level protocols:
+
+- canonicalize the JSON with RFC 8785 (JCS),
+- hash canonical UTF-8 bytes with `sha256`,
+- represent digests as lowercase hex.
+
+`AgentIdentity.v1` itself does not require an embedded signature field in v1.
+
+## Required fields
+
+- `schemaVersion` (const: `AgentIdentity.v1`)
+- `agentId` (stable identifier)
+- `tenantId` (tenant scope)
+- `displayName` (human-readable label)
+- `status` (`active` | `suspended` | `revoked`)
+- `owner` (operator linkage)
+- `keys` (primary verification key descriptor)
+- `capabilities` (declared capability identifiers)
+- `createdAt` / `updatedAt` (ISO date-time)
+
+## Owner linkage
+
+`owner` binds the autonomous identity to an accountable controller:
+
+- `ownerType`: `human` | `business` | `service`
+- `ownerId`: stable owner identifier
+
+## Key descriptor
+
+`keys` defines the active verification material for the identity:
+
+- `keyId`: derived or assigned key identifier
+- `algorithm`: currently `ed25519`
+- `publicKeyPem`: PEM-encoded public key
+
+## Optional policy hints
+
+`walletPolicy` carries optional spend/approval constraints for downstream settlement systems:
+
+- `maxPerTransactionCents`
+- `maxDailyCents`
+- `requireApprovalAboveCents`
+
+These fields are optional and non-normative in v1. Implementations MAY enforce them when creating holds/settlements (for example, rejecting a settlement when `amountCents > maxPerTransactionCents` or when an out-of-band approval gate is required above `requireApprovalAboveCents`).
+
+Implementation note (this repo): the Settld API enforces `maxPerTransactionCents`, `maxDailyCents`, and `requireApprovalAboveCents` on settlement/hold creation paths that lock escrow from an agent wallet.

package/docs/spec/AgentPassport.v1.md

@@ -0,0 +1,95 @@
+# AgentPassport.v1
+
+`AgentPassport.v1` defines the portable delegation identity envelope for an autonomous economic actor.
+
+Status: Draft (architecture target; not fully enforced in runtime yet).
+
+## Purpose
+
+`AgentPassport.v1` is the root identity contract used to answer:
+
+- which principal ultimately backs this agent,
+- which keyset currently represents the agent,
+- which delegation root authorizes spend/actions,
+- which capability credentials the agent can present,
+- which policy envelope bounds autonomous execution.
+
+The object is designed to be stable, hash-addressable, and portable across hosts/runtimes.
+
+## Required fields
+
+- `schemaVersion` (const: `AgentPassport.v1`)
+- `passportId`
+- `agentId`
+- `tenantId`
+- `principalRef`
+- `identityAnchors`
+- `delegationRoot`
+- `policyEnvelope`
+- `status`
+- `createdAt`
+- `updatedAt`
+
+## Principal binding
+
+`principalRef` binds the agent to an accountable sponsor:
+
+- `principalType`: `human` | `business` | `service` | `dao`
+- `principalId`: stable principal identifier
+- `jurisdiction`: optional compliance hint (for policy packs)
+
+## Identity anchors
+
+`identityAnchors` defines key discovery and verification roots:
+
+- `did` (optional, DID URI)
+- `jwksUri` (HTTPS URL)
+- `activeKeyId`
+- `keysetHash` (sha256 hex over normalized JWK set)
+
+## Delegation root
+
+`delegationRoot` pins the root authority chain used for autonomous actions:
+
+- `rootGrantId`
+- `rootGrantHash`
+- `issuedAt`
+- `expiresAt` (nullable)
+- `revokedAt` (nullable)
+
+A revoked root (`revokedAt != null`) MUST be treated as non-executable by strict policy engines.
+
+## Capability credentials
+
+`capabilityCredentials` is an optional array of machine-verifiable capability claims. Entries carry:
+
+- `credentialType`
+- `issuer`
+- `credentialRef`
+- `credentialHash`
+- `issuedAt`
+- `expiresAt` (nullable)
+
+## Policy envelope
+
+`policyEnvelope` binds baseline controls before request-level decisions:
+
+- `maxPerCallCents`
+- `maxDailyCents`
+- `allowedRiskClasses` (`read|compute|action|financial`)
+- `requireApprovalAboveCents` (nullable)
+- `allowlistRefs` (optional references to provider/tool policy sets)
+
+## Canonicalization + hashing
+
+When used as an input to signatures or binding hashes:
+
+1. canonicalize JSON with RFC 8785 (JCS),
+2. hash canonical UTF-8 bytes with `sha256`,
+3. encode as lowercase hex.
+
+`AgentPassport.v1` does not require an embedded signature field in v1; signatures are expected in detached envelopes at transport/control layers.
+
+## Schema
+
+See `docs/spec/schemas/AgentPassport.v1.schema.json`.

package/docs/spec/AgentReputation.v1.md

@@ -0,0 +1,59 @@
+# AgentReputation.v1
+
+`AgentReputation.v1` defines a deterministic trust snapshot for a tenant-scoped agent identity.
+
+It is computed from:
+
+- run lifecycle outcomes (`AgentRun.v1`),
+- evidence coverage signals (`AgentRun.v1.evidenceRefs`),
+- escrow/settlement outcomes (`AgentRunSettlement.v1`).
+
+## Schema
+
+See `schemas/AgentReputation.v1.schema.json`.
+
+## Required fields
+
+- `schemaVersion` (const: `AgentReputation.v1`)
+- `agentId`
+- `tenantId`
+- `trustScore` (`0..100`)
+- `riskTier` (`low|guarded|elevated|high`)
+- run counters (`totalRuns`, `terminalRuns`, `createdRuns`, `runningRuns`, `completedRuns`, `failedRuns`)
+- evidence + settlement counters
+- score rates (`runCompletionRatePct`, `evidenceCoverageRatePct`, `settlementReleaseRatePct`)
+- `scoreBreakdown`
+- `computedAt`
+
+## Score semantics (v1)
+
+`trustScore` is a weighted score over bounded integer components:
+
+- run quality (terminal completion rate),
+- settlement quality (release rate over resolved settlements),
+- evidence quality (terminal runs carrying evidence),
+- activity score (bounded by run volume).
+
+Weights in v1 are deterministic and fixed by implementation:
+
+- run quality: 55%
+- settlement quality: 30%
+- evidence quality: 10%
+- activity score: 5%
+
+## Rate nullability
+
+The following fields are `null` when no denominator exists:
+
+- `runCompletionRatePct` (no terminal runs),
+- `evidenceCoverageRatePct` (no terminal runs),
+- `settlementReleaseRatePct` (no resolved settlements),
+- `avgRunDurationMs` (no terminal runs with valid start/end timestamps).
+
+## Canonicalization and hashing
+
+When hashed/signed by higher-level protocols:
+
+- canonicalize JSON via RFC 8785 (JCS),
+- hash canonical UTF-8 bytes using `sha256`,
+- emit lowercase hex digests.