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.
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. |
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"
}
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 Write Gate · product brief for buyers
- Security & data handling · what we see and do not