Schema · write_intent.v1

Write Intent schema

Clear, versioned metadata every orchestrator emits to check_write before a mutating side effect. TekCapitol™ does not query the system of record.

Download JSON Schema Check Write™ design Salesforce Check Write™ integration Security & data handling

Identity

schemaVersion	`write_intent.v1` (const)
Canonical JSON Schema	`/schema/write-intent/v1/write-intent.v1.json`
Alias	`/schemas/write-intent-v1.json`
$id	`https://tekcapitol.com/schema/write-intent/v1/write-intent.v1.json`

Required fields

Field	Meaning
`schemaVersion`	Must be `write_intent.v1`.
`system`	System of record id (e.g. Salesforce, SAP, Snowflake).
`objectType`	Object / entity type (e.g. Opportunity).
`objectRef`	Record id in that system.
`intendedChanges`	Array of `{ field, newValue }`. At least one change.

Recommended fields

Field	Meaning
`authority`	Independent entitlement / SoR value the write must match. Prefer `billing_sor` / `crm_entitlement`, not prompt text.
`authority.checkedAt`	ISO-8601 time the orchestrator read authority.
`authority.maxAgeMs`	Freshness window for `checkedAt`.
`authority.stalePolicy`	`warn` \| `pause` \| `block`. Default in Live API: `warn`.
`freshness.recordVersion`	e.g. Salesforce `SystemModstamp` or row version.
`freshness.stampType`	e.g. `SystemModstamp`, `hash`, `etag`.
`freshness.hash`	Optional hash of critical fields known to the orchestrator.
`agentIdentity`	Which agent / service identity is writing.
`workflowId` / `runId`	Correlation for Trace and audit.
`requireApproval`	If true, Check Write™ returns `pause` even when values match (HITL).
`idempotencyKey`	Optional dedupe key for the write attempt.
`writeIntentEnvelope`	Signed attestation envelope for identity, workflow attestation, and authority revalidation. Includes the `signature` and is verified by TC Protect.

Freshness and authorityStalePolicy

The gate is only as strong as the signals the orchestrator emits. If the orchestrator only has stale context and sends no freshness window, the freshness check is weak.

stalePolicy	When authority age > maxAgeMs
`warn`	Decision may still allow; response flags freshness warn. Default for backward compatibility.
`pause`	Decision `pause`. Do not write until a human clears or authority is re-read.
`block`	Decision `block`. Fail closed on stale authority.

High-assurance workflows should set authority.stalePolicy to pause or block, and emit a lightweight SoR stamp (for example orchestrator reads Salesforce SystemModstamp only and includes it in freshness). TekCapitol™ never opens Salesforce for you.

Minimal example

{
  "schemaVersion": "write_intent.v1",
  "system": "Salesforce",
  "objectType": "Opportunity",
  "objectRef": "006XXXXXXXXXXXX",
  "intendedChanges": [
    { "field": "StageName", "newValue": "Approved" }
  ],
  "authority": {
    "value": "eligible",
    "source": "billing_sor",
    "checkedAt": "2026-08-11T18:00:00.000Z",
    "maxAgeMs": 5000,
    "stalePolicy": "pause"
  },
  "freshness": {
    "recordVersion": "2026-08-11T17:59:58.000Z",
    "stampType": "SystemModstamp"
  },
  "agentIdentity": "renewal-agent-v3",
  "workflowId": "sf-renewal-opp",
  "runId": "run_abc123"
}

Full writeIntentEnvelope (signed attestation)

The envelope shape below matches what the SDK builds into check_write input. TC Protect™ verifies the signature, then attests the JWT payload (agent, workflow, write, and context) against the envelope fields.

{
  "run_id": "run_123",
  "agent": {
    "agent_id": "renewal-agent-17",
    "agent_version": "2.4.1",
    "service_account": "svc-renewal-prod",
    "identity_provider": "okta-workload",
    "token_issuer": "https://issuer.example.com"
  },
  "workflow": {
    "workflow_id": "salesforce-renewal",
    "workflow_version": "3.2",
    "orchestrator": "langgraph",
    "deployment_id": "prod-west-1",
    "definition_hash": "sha256:demo_definition_fingerprint"
  },
  "actor": {
    "on_behalf_of": "user_456"
  },
  "write": {
    "system": "Salesforce",
    "object": "Opportunity",
    "record_id": "006XXXXXXXXXXXX",
    "operation": "update",
    "fields": {
      "StageName": "Approved"
    }
  },
  "context": {
    "approval_id": "approval_789",
    "approval_expires_at": "2026-08-19T12:25:00.000Z",
    "approval_checked_at": "2026-08-19T12:00:00.000Z",
    "policy_version": "2026-08-19",
    "timestamp": "2026-08-19T12:00:00.000Z"
  },
  "signature": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9........"
}

Signature validation (JWT and JWKS)

Preferred: signature is a JWT (JWS compact) string with header.payload.signature. TC Protect™ verifies alg and validates the signature.
HS256: verifies using signing_secret in the Agent Registry.
RS256 and ES256: verifies using a public key derived from the Agent Registry trust material:
- JWKS keys (matched by JWT kid when present)
- or inline public_key_pem / certificate_pem
Issuer attestation: when the Agent Registry sets expected_issuer, TC Protect compares it to the JWT iss claim.
Payload attestation: if the JWT payload fields do not exactly match the envelope fields (agent, workflow, write, and context), TC Protect blocks with SIGNATURE_INVALID.
Legacy fallback: if signature is not a JWT compact string, TC Protect uses legacy HMAC-SHA256 hex verification over canonicalized envelope payload (excluding signature).

SDK helpers

Private package @tekcapitol/tc-protect-sdk (folder drop / file dependency): buildWriteIntent, withRecordFreshness, evaluateWriteIntent, guardedWrite. See Check Write™ design.

Also in Docs

Check Write™ design v0 · emission path, decision API, audit
Salesforce Check Write™ integration · product brief for buyers
SAP Check Write™ integration · product brief for buyers
Snowflake Check Write™ integration · product brief for buyers
ServiceNow Check Write™ integration · product brief for buyers
Security & data handling · what we see and do not

Breaking changes ship as write_intent.v2 at a new URL under /schema/write-intent/v2/. v1 remains stable.