settld 0.1.2 → 0.2.0

package/docs/spec/AgentRunSettlement.v1.md

@@ -0,0 +1,52 @@
+# AgentRunSettlement.v1
+
+`AgentRunSettlement.v1` defines the escrow/settlement state for one `AgentRun.v1`.
+
+Related contracts:
+- `ESCROW_NETTING_INVARIANTS.md` (money conservation + partition rules)
+- `MONEY_RAIL_STATE_MACHINE.md` (external payout/collection lifecycle)
+
+It binds run execution outcomes to deterministic money movement:
+
+- `locked`: escrow funded and awaiting run terminal outcome.
+- `released`: run completed and escrow released to the run agent.
+- `refunded`: run failed and escrow refunded to payer.
+
+Related decision/finality artifacts:
+
+- `SettlementDecisionRecord.v1|v2` and `SettlementReceipt.v1` bind decision provenance and finality receipts to one settlement.
+
+## Schema
+
+See `schemas/AgentRunSettlement.v1.schema.json`.
+
+## Required fields
+
+- `schemaVersion` (const: `AgentRunSettlement.v1`)
+- `settlementId`
+- `runId`
+- `tenantId`
+- `agentId` (payee / run owner)
+- `payerAgentId`
+- `amountCents`
+- `currency`
+- `status` (`locked|released|refunded`)
+- `lockedAt`
+- `revision`
+- `createdAt`
+- `updatedAt`
+
+## Resolution semantics
+
+- Settlement is initialized as `locked`.
+- Settlement may resolve exactly once to `released` or `refunded`.
+- `resolvedAt` and `resolutionEventId` are populated on resolution.
+- `runStatus` captures the terminal run state that triggered resolution.
+
+## 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.

package/docs/spec/AgentWallet.v1.md

@@ -0,0 +1,43 @@
+# AgentWallet.v1
+
+`AgentWallet.v1` defines the deterministic balance snapshot for an autonomous agent.
+
+The wallet is tenant-scoped and currency-scoped, and is intended for:
+
+- funding and spend tracking,
+- escrow lock accounting,
+- deterministic settlement transitions.
+
+## Schema
+
+See `schemas/AgentWallet.v1.schema.json`.
+
+## Required fields
+
+- `schemaVersion` (const: `AgentWallet.v1`)
+- `walletId`
+- `agentId`
+- `tenantId`
+- `currency`
+- `availableCents`
+- `escrowLockedCents`
+- `totalDebitedCents`
+- `totalCreditedCents`
+- `revision`
+- `createdAt`
+- `updatedAt`
+
+## Invariants (v1)
+
+- `availableCents` and `escrowLockedCents` are non-negative integers.
+- Escrow locks move value from `availableCents` to `escrowLockedCents`.
+- Releases reduce payer `escrowLockedCents` and increase payee `availableCents`.
+- Refunds reduce payer `escrowLockedCents` and increase payer `availableCents`.
+
+## 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.

package/docs/spec/AgreementDelegation.v1.md

@@ -0,0 +1,109 @@
+# AgreementDelegation.v1
+
+`AgreementDelegation.v1` defines a deterministic, hash-addressable link between a **parent agreement** and a **child agreement** created via delegation in a multi-hop agent chain.
+
+It exists to make compositional settlement possible:
+
+- prove parent -> child provenance without database traversal,
+- enforce delegation depth limits (prevent unbounded chains),
+- carry a budget cap for the child agreement derived from the parent.
+
+## Schema
+
+See `schemas/AgreementDelegation.v1.schema.json`.
+
+## Canonicalization and hashing
+
+When computing `delegationHash`:
+
+- canonicalize JSON via RFC 8785 (JCS),
+- hash canonical UTF-8 bytes via `sha256`,
+- represent as lowercase hex.
+
+`delegationHash` is computed over the immutable core fields and intentionally excludes mutable lifecycle fields:
+
+Excluded fields:
+- `delegationHash`
+- `status`
+- `resolvedAt`
+- `updatedAt`
+- `revision`
+- `metadata`
+
+## Required fields
+
+- `schemaVersion` (const: `AgreementDelegation.v1`)
+- `delegationId` (stable identifier, not derived from hash)
+- `tenantId`
+- `parentAgreementHash` (sha256 hex)
+- `childAgreementHash` (sha256 hex)
+- `delegatorAgentId` (agent that created/authorized the delegation)
+- `delegateeAgentId` (agent that received the delegation authority)
+- `budgetCapCents` (positive integer)
+- `currency`
+- `delegationDepth` (non-negative integer; depth of the child agreement relative to the root)
+- `maxDelegationDepth` (non-negative integer)
+- `createdAt` (ISO date-time)
+- `delegationHash` (sha256 hex of immutable core)
+- `status` (`active` | `settled` | `revoked`)
+- `revision` (non-negative integer)
+- `updatedAt` (ISO date-time)
+
+## Optional fields
+
+- `ancestorChain` (ordered array of sha256 hex agreement hashes; enables offline audit without traversal)
+- `resolvedAt` (ISO date-time, set when `status` transitions out of `active`)
+- `metadata` (free-form object; non-normative)
+
+## Invariants
+
+Implementations MUST enforce:
+
+- `budgetCapCents > 0`
+- `delegationDepth <= maxDelegationDepth`
+- `parentAgreementHash != childAgreementHash`
+
+If `ancestorChain` is provided, implementations MUST enforce:
+
+- `ancestorChain.length == delegationDepth`
+- `ancestorChain[ancestorChain.length - 1] == parentAgreementHash`
+- no duplicates in `ancestorChain` (cycle defense)
+
+Budget-capping is compositional:
+
+- The caller/system that creates a child delegation MUST ensure `budgetCapCents` is <= the parent agreement's **remaining** budget at creation time.
+
+## Deterministic pre-check failure codes
+
+Some API workflows may bind settlement to a delegation graph and run deterministic pre-checks before a release/refund decision.
+
+When those checks fail, implementations SHOULD return a stable `code` that is suitable for programmatic handling:
+
+- `AGREEMENT_DELEGATION_CYCLE` — A cycle was detected in the parent-chain for the bound agreement.
+- `AGREEMENT_DELEGATION_MULTIPLE_PARENTS` — Multiple parents were found for the same `childAgreementHash` (graph is not a function).
+
+## Deterministic execution plans (idempotent)
+
+Settld exposes deterministic traversal plans for execution:
+
+- `cascadeSettlementCheck(fromChildHash)` returns a bottom-up parent chain.
+- `refundUnwindCheck(fromParentHash)` returns a top-down child chain.
+
+Execution helpers apply those plans idempotently:
+
+- Release execution resolves traversed delegations to `status=settled`.
+- Unwind execution resolves traversed delegations to `status=revoked`.
+- Re-running the same execution against already-resolved delegations is a no-op.
+
+Implementations SHOULD reject conflicting terminal transitions (for example attempting `settled` on a delegation already `revoked`) and preserve a simple ledger invariant:
+
+- `active + settled + revoked == total`.
+
+## Lifecycle semantics
+
+`AgreementDelegation.v1` is intended to be created as `status=active` and later resolved:
+
+- `status=settled`: child agreement has been settled and no further delegation actions should be taken.
+- `status=revoked`: delegation authority is revoked (for example emergency revoke).
+
+Status transitions mutate only lifecycle fields and MUST NOT change `delegationHash`.

package/docs/spec/ArbitrationCase.v1.md

@@ -0,0 +1,67 @@
+# ArbitrationCase.v1
+
+`ArbitrationCase.v1` defines the protocol object for a formal dispute arbitration case.
+
+It is the canonical case container used by the arbitration layer to bind:
+
+- the disputed run/settlement identifiers,
+- participating parties and assigned arbiter,
+- evidence references, and
+- optional appeal lineage.
+
+## Schema
+
+See `schemas/ArbitrationCase.v1.schema.json`.
+
+## Required fields
+
+- `schemaVersion` (const: `ArbitrationCase.v1`)
+- `caseId`
+- `tenantId`
+- `runId`
+- `settlementId`
+- `disputeId`
+- `claimantAgentId`
+- `respondentAgentId`
+- `status` (`open|under_review|verdict_issued|closed`)
+- `openedAt`
+- `evidenceRefs` (deterministic, unique set)
+- `revision`
+- `createdAt`
+- `updatedAt`
+
+## Appeal references
+
+Appeal lineage is represented with optional `appealRef`:
+
+- `parentCaseId` (required when `appealRef` is present)
+- `parentVerdictId` (optional)
+- `reason` (optional summary)
+
+This keeps appeal linkage explicit without mutating the parent case.
+
+## Metadata conventions
+
+`metadata` is intentionally schemaless to allow subject-specific conventions.
+
+### Tool-call disputes (Sprint 21)
+
+For tool-call holdback disputes, `metadata` MUST include:
+
+- `caseType`: `"tool_call"`
+- `agreementHash`: sha256 hex (lowercase)
+- `receiptHash`: sha256 hex (lowercase)
+- `holdHash`: sha256 hex (lowercase)
+
+These fields are used to:
+
+- freeze holdback auto-release while the case is not closed, and
+- bind deterministic adjustments to the disputed economic subject.
+
+## 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.

package/docs/spec/ArbitrationOutcomeMapping.v1.md

@@ -0,0 +1,62 @@
+# ArbitrationOutcomeMapping.v1
+
+This document freezes deterministic mapping from dispute/arbitration outcomes to settlement directives in Trust OS v1.
+
+## Purpose
+
+Dispute outcomes must produce one unambiguous financial directive so settlement resolution is:
+
+- deterministic,
+- replay-safe,
+- auditable with stable evidence traces.
+
+## Outcome to directive mapping
+
+Input: `AgentRunSettlement.v1.disputeResolution` + settlement `amountCents`
+
+- `outcome=accepted`
+  - directive: `status=released`
+  - `releaseRatePct=100`
+  - `releasedAmountCents=amountCents`
+  - `refundedAmountCents=0`
+- `outcome=rejected`
+  - directive: `status=refunded`
+  - `releaseRatePct=0`
+  - `releasedAmountCents=0`
+  - `refundedAmountCents=amountCents`
+- `outcome=partial`
+  - financial outcome: `reversal`
+  - settlement directive: `status=released`
+  - requires `releaseRatePct` integer in range `1..99`
+  - `releasedAmountCents=floor(amountCents * releaseRatePct / 100)`
+  - `refundedAmountCents=amountCents - releasedAmountCents`
+  - both released/refunded amounts must be non-zero (true split)
+
+## Validation invariants
+
+- `accepted` may include `releaseRatePct` only as `100`.
+- `rejected` may include `releaseRatePct` only as `0`.
+- `partial` must include `releaseRatePct` in `1..99`.
+- `withdrawn|unresolved` must not include `releaseRatePct` and cannot derive settlement directives.
+- `amountCents` must be a positive safe integer when deriving directives.
+
+Invalid combinations fail-closed with stable error code `DISPUTE_OUTCOME_DIRECTIVE_INVALID`.
+
+## Resolve request guardrails
+
+For `/runs/{runId}/settlement/resolve` when a dispute directive exists:
+
+- request `status` may be omitted (derived status is authoritative),
+- explicit `status` must equal derived status,
+- explicit `releaseRatePct`, `releasedAmountCents`, and `refundedAmountCents` must match derived values exactly.
+- if settlement is already resolved and dispute directive is present, dispute status must be `closed`.
+
+Status mismatch fails with `DISPUTE_OUTCOME_STATUS_MISMATCH`.
+Directive amount/rate mismatch fails with `DISPUTE_OUTCOME_AMOUNT_MISMATCH`.
+Resolved-settlement directive precondition mismatch fails with `TRANSITION_ILLEGAL`.
+
+## Determinism requirements
+
+- identical dispute inputs must generate identical directives across retries.
+- idempotency replay for resolve operations must return the same settlement and decision traces.
+- decision traces should include the resolved `disputeSettlementDirective` for audit.

package/docs/spec/ArbitrationVerdict.v1.md

@@ -0,0 +1,60 @@
+# ArbitrationVerdict.v1
+
+`ArbitrationVerdict.v1` defines the signed verdict artifact for an `ArbitrationCase.v1`.
+
+It records deterministic decision output from an arbiter, including:
+
+- final outcome (`accepted|rejected|partial`),
+- settlement release partition hint (`releaseRatePct`),
+- rationale and cited evidence references,
+- signature material, and
+- optional appeal linkage.
+
+## Schema
+
+See `schemas/ArbitrationVerdict.v1.schema.json`.
+
+## Required fields
+
+- `schemaVersion` (const: `ArbitrationVerdict.v1`)
+- `verdictId`
+- `caseId`
+- `tenantId`
+- `runId`
+- `settlementId`
+- `disputeId`
+- `arbiterAgentId`
+- `outcome` (`accepted|rejected|partial`)
+- `releaseRatePct` (integer `0..100`)
+- `rationale`
+- `evidenceRefs`
+- `issuedAt`
+- `signature` (deterministic signing envelope)
+- `revision`
+- `createdAt`
+- `updatedAt`
+
+## Signature envelope
+
+`signature` includes:
+
+- `algorithm` (`ed25519`)
+- `signerKeyId`
+- `verdictHash` (hash of canonical verdict core)
+- `signature` (base64 signature)
+
+## Appeal references
+
+If this verdict participates in an appeal chain, include optional `appealRef`:
+
+- `appealCaseId`
+- `parentVerdictId`
+- `reason` (optional)
+
+## 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.

package/docs/spec/BundleHeadAttestation.v1.md

@@ -0,0 +1,32 @@
+# BundleHeadAttestation.v1
+
+`BundleHeadAttestation.v1` is canonical JSON stored at `attestation/bundle_head_attestation.json`.
+
+In strict mode, finance-grade bundles require this attestation.
+
+## Purpose
+
+- Commit to a specific bundle by signing:
+  - `manifestHash`
+  - and the relevant nested heads (e.g., FinancePack commits to MonthProof manifest/attestation).
+
+## Core fields
+
+- `schemaVersion = "BundleHeadAttestation.v1"`
+- `kind`: the bundle kind/type (e.g. `JobProofBundle.v1`, `MonthProofBundle.v1`, `FinancePackBundle.v1`)
+- `tenantId`
+- `scope`: kind-specific scope object (e.g. `{jobId}` or `{period}`)
+- `generatedAt`: bundle generation time (best-effort timestamp)
+- `manifestHash`: bundle manifest hash
+- `heads`: kind-specific head commitments
+- `timestampProof` (optional): a trustworthy signing time proof used for revocation/rotation historical acceptance checks
+- `signedAt`: attestation signing time (server time)
+- `signerKeyId`
+- `attestationHash`: canonical hash of the attestation core (signature excluded)
+- `signature`: base64 Ed25519 signature over `attestationHash`
+
+## Validity requirements (strict mode)
+
+- Signature must verify with the governed server key identified by `signerKeyId`.
+- The signer key must be governed/valid per the embedded governance stream rules.
+- `manifestHash` must match the bundle’s computed manifest hash.

package/docs/spec/CANONICAL_JSON.md

@@ -0,0 +1,31 @@
+# Canonical JSON
+
+Settld hashes and signs canonical JSON to avoid ambiguity across runtimes/languages.
+
+## Canonicalization algorithm
+
+Settld uses **RFC 8785 (JCS — JSON Canonicalization Scheme)** as the canonicalization contract for all protocol-critical hashes/signatures.
+
+In this repo, “canonical JSON” means the UTF-8 bytes of the JCS canonical form.
+
+Given an input value (a JSON value):
+
+- `null`, `string`, `boolean` serialize as-is.
+- `number` must be finite and must not be `-0` (protocol rejects these).
+- `array` preserves element order; each element is canonicalized recursively.
+- `object` must be a plain object (prototype is `Object.prototype` or `null`), with no symbol keys.
+  - Keys are sorted ascending (lexicographic).
+  - Values are canonicalized recursively.
+
+The canonical form is serialized as JSON (no whitespace) per JCS.
+
+### Optional fields
+
+- JSON has no `undefined`. Protocol objects MUST NOT include `undefined` in hashed/signed payloads.
+- “Field not present” is semantically different from “field present with `null`”. Protocol surfaces SHOULD omit optional fields when absent, and use `null` only when the spec explicitly calls for it.
+
+## Hash rule
+
+When a spec says **“hash the object”**, it means:
+
+`sha256_hex( utf8( canonical_json_stringify(object) ) )`

package/docs/spec/CRYPTOGRAPHY.md

@@ -0,0 +1,61 @@
+# Cryptography Inventory (v1)
+
+This document is an explicit inventory of cryptographic primitives and byte-level rules used by the protocol/toolchain.
+
+## Canonicalization (JSON)
+
+- **Standard**: RFC 8785 (JCS).
+- **Bytes hashed for JSON objects**: UTF-8 bytes of the canonical JSON string.
+- Spec: `CANONICAL_JSON.md`
+- Implementations:
+  - Verifier canonicalization: `packages/artifact-verify/src/canonical-json.js`
+  - Bundler canonicalization: `src/core/canonical-json.js`
+
+## Hashing
+
+- **Algorithm**: SHA-256.
+- **Encoding**: lowercase hex.
+- **Manifest file hashing**: raw file bytes (no normalization).
+  - Verifier: `packages/artifact-verify/src/hash-file.js`
+- **JSON object hashing**: SHA-256 over UTF-8 bytes of RFC 8785 canonical JSON.
+  - Verifier helper: `packages/artifact-verify/src/crypto.js`
+  - Bundler helper: `src/core/crypto.js`
+
+## Signatures
+
+### Governance-root signatures
+
+Used to sign governance policy (v2) and revocation lists.
+
+- **Algorithm**: Ed25519.
+- **Signed message**: the hex SHA-256 digest of canonical JSON (see above), passed as bytes to Ed25519 verification.
+- Verifier implementation: `packages/artifact-verify/src/crypto.js:16`
+
+### Event signer / server signer signatures
+
+Used for:
+
+- bundle head attestation (`attestation/bundle_head_attestation.json`)
+- strict verification report (`verify/verification_report.json`)
+- timestamp proofs (optional, when present)
+
+Algorithm and verification semantics are the same: Ed25519 over the hash digest bytes.
+
+## Key formats
+
+- **Public keys**: PEM-encoded public keys stored as strings (for verification).
+- **Private keys**: PEM-encoded private keys used only by bundlers/signers (not shipped in bundles).
+- Key IDs: stable string identifiers (e.g., `key_…`) used as lookup keys in policy/trust maps.
+
+## Algorithm agility stance (v1)
+
+For v1 protocol objects, supported signature algorithms are intentionally narrow:
+
+- Governance policy declares allowed algorithms (currently `ed25519`).
+- Verifiers MUST reject signatures/policies requiring algorithms they do not implement.
+
+Adding new algorithms is a protocol change and should be introduced via:
+
+- new protocol object versions (preferred), or
+- an explicit versioned policy expansion plus conformance pack updates.
+

package/docs/spec/ClosePack.v1.md

@@ -0,0 +1,49 @@
+# ClosePack.v1
+
+`ClosePack.v1` is a **pre-dispute invoice package**: a single bundle a buyer can archive and later re-verify offline to answer:
+
+- “What was billed?”
+- “What work proof was bound to the bill?”
+- “What evidence files were referenced?”
+- (Optionally) “Did this job meet the SLA?” and “Did it meet acceptance criteria?”
+
+ClosePack is a **bundle kind** with its own `manifest.json`, head attestation, and verification report. It **embeds** an `InvoiceBundle.v1` directory tree.
+
+## On-disk layout (v1)
+
+- `settld.json` — header with `type="ClosePack.v1"` and binding inputs (see below).
+- `manifest.json` — `ClosePackManifest.v1` (commits to all files except `verify/**`).
+- `attestation/bundle_head_attestation.json` — `BundleHeadAttestation.v1` for `kind="ClosePack.v1"`.
+- `verify/verification_report.json` — `VerificationReport.v1` bound to this ClosePack’s `manifestHash` and head attestation.
+- `payload/invoice_bundle/**` — embedded `InvoiceBundle.v1` (byte-for-byte directory tree copy).
+- `evidence/evidence_index.json` — `EvidenceIndex.v1` (required).
+- Optional “explainable computations” (portable + recomputable):
+  - `sla/sla_definition.json` — `SlaDefinition.v1`
+  - `sla/sla_evaluation.json` — `SlaEvaluation.v1`
+  - `acceptance/acceptance_criteria.json` — `AcceptanceCriteria.v1`
+  - `acceptance/acceptance_evaluation.json` — `AcceptanceEvaluation.v1`
+
+## Hashing + circularity
+
+ClosePack manifests intentionally exclude `verify/**` (same rationale as other bundle kinds) so verification outputs do not create circular hashing.
+
+## Binding inputs (ClosePack header)
+
+`settld.json` includes inputs that bind the ClosePack to the embedded Invoice bundle:
+
+- `invoiceBundle.embeddedPath` (constant path within ClosePack, v1)
+- `invoiceBundle.manifestHash`
+- `invoiceBundle.headAttestationHash`
+
+Verifiers must ensure these match the embedded Invoice bundle instance at `payload/invoice_bundle/**`.
+
+## Strict vs non-strict
+
+- **Strict** mode:
+  - ClosePack must be structurally complete and internally consistent.
+  - Embedded `InvoiceBundle.v1` must strictly verify.
+  - If `sla/*` or `acceptance/*` evaluation surfaces are present, the verifier must recompute them and require exact match.
+- **Non-strict** mode:
+  - Missing optional `sla/*` and `acceptance/*` surfaces may be accepted with structured warnings (see `WARNINGS.md`).
+  - Evidence index is still expected to be present (ClosePack’s core value proposition).
+

package/docs/spec/ClosePackManifest.v1.md

@@ -0,0 +1,24 @@
+# ClosePackManifest.v1
+
+This manifest is stored at `manifest.json` within ClosePack bundles.
+
+## Hashing contract
+
+- `hashing.schemaVersion = "ClosePackManifestHash.v1"`
+- file order: `path_asc`
+- excludes: `["verify/**"]`
+
+Rationale: `verify/verification_report.json` is a derived output that binds to `manifestHash`, so including `verify/**` in the manifest would create circular hashing.
+
+## manifestHash
+
+`manifestHash = sha256_hex( canonical_json_stringify(manifest_without_hash) )`
+
+## File entries
+
+`files[]` entries include:
+
+- `name` (path relative to ClosePack root)
+- `sha256` (hex sha256 of raw file bytes)
+- `bytes` (byte length)
+

package/docs/spec/DelegationGrant.v1.md

@@ -0,0 +1,90 @@
+# DelegationGrant.v1
+
+`DelegationGrant.v1` defines a deterministic delegated-authority grant between two agents.
+
+Status: Draft (architecture target; not fully enforced in runtime yet).
+
+## Purpose
+
+`DelegationGrant.v1` encodes bounded authority transfer for autonomous execution:
+
+- who delegated to whom,
+- what capability/risk scope is allowed,
+- what spend envelope is permitted,
+- how deep the delegation chain can extend,
+- when the grant is valid and revocable.
+
+## Required fields
+
+- `schemaVersion` (const: `DelegationGrant.v1`)
+- `grantId`
+- `tenantId`
+- `delegatorAgentId`
+- `delegateeAgentId`
+- `scope`
+- `spendLimit`
+- `chainBinding`
+- `validity`
+- `revocation`
+- `createdAt`
+- `grantHash`
+
+## Scope model
+
+`scope` defines the maximal authority window:
+
+- `allowedProviderIds` (optional)
+- `allowedToolIds` (optional)
+- `allowedRiskClasses` (required)
+- `sideEffectingAllowed` (required boolean)
+
+If `sideEffectingAllowed=false`, strict policy engines MUST reject side-effecting execution intents even if tool/provider is allowlisted.
+
+## Spend envelope
+
+`spendLimit` defines bounded economic authority:
+
+- `currency`
+- `maxPerCallCents`
+- `maxTotalCents`
+
+Implementations SHOULD track cumulative spend against `maxTotalCents` using immutable receipt references.
+
+## Chain binding
+
+`chainBinding` binds grant placement in delegation topology:
+
+- `rootGrantHash`
+- `parentGrantHash` (nullable)
+- `depth`
+- `maxDelegationDepth`
+
+A child grant is valid only when `depth <= maxDelegationDepth` and parent is valid/non-revoked.
+
+## Validity + revocation
+
+`validity`:
+
+- `issuedAt`
+- `notBefore`
+- `expiresAt`
+
+`revocation`:
+
+- `revocable`
+- `revokedAt` (nullable)
+- `revocationReasonCode` (nullable)
+
+## Canonicalization + hashing
+
+`grantHash` is computed over canonical JSON of the full object excluding `grantHash`:
+
+1. canonicalize JSON with RFC 8785 (JCS),
+2. hash canonical UTF-8 bytes using `sha256`,
+3. encode lowercase hex.
+
+Detached signatures may be applied by transport/control layers; v1 does not require an embedded signature field.
+
+## Schema
+
+See `docs/spec/schemas/DelegationGrant.v1.schema.json`.