Controlled developer pilot

Govern one real action before expanding the surface.

This guide covers the narrow CordonRail path we currently support: propose a typed action, apply policy, obtain a named human decision where required, record the external outcome, and export evidence someone else can verify.

First action quickstart

  1. Create a CordonRail workspace and open the guided setup.
  2. Create an API key with read:governed and write:governed. The secret is shown once; store it outside source control.
  3. Hash the canonical private arguments in your own system. Send the hash and only the non-secret facts a reviewer needs.
  4. Begin shadow observation and submit the synthetic export once. CordonRail records what the standard policy would have held without treating that counterfactual as an approval.
  5. End observation, resubmit the same typed contract with a new action identity, and let the standard policy hold it for a named person.
  6. Decide in the CordonRail queue, request execution authority, perform the external effect in your integration, then record the exact outcome or reconciliation state.
  7. Export the resulting record and open its independent verification link without relying on the originating account.
curl --fail-with-body -X POST \
  "https://api.cordonrail.com/api/v1/governed/actions" \
  -H "Authorization: Bearer $CORDONRAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: export-synthetic-8812" \
  --data '{
    "actionId": "export-synthetic-8812",
    "actionSchemaId": "customer.export.v1",
    "agentRef": "customer-ops-agent",
    "actionClass": "data_export",
    "summary": "Prepare a synthetic customer export",
    "argumentsHash": "<sha256-of-private-canonical-arguments>",
    "materialArguments": {
      "customerRef": "synthetic-customer-8812",
      "format": "json",
      "fieldSet": "service_history,invoices",
      "purpose": "portability rehearsal"
    },
    "materialFactsSource": {
      "kind": "integration_declared",
      "integrationId": "customer-export-adapter",
      "integrationVersion": "0.1.0"
    }
  }'

Do not paste customer data into the example. Use synthetic facts until the deployment reports durable admission and your production use has been agreed separately.

Retry contract: actionId is the durable proposal identity. If you send an Idempotency-Key, it must match actionId. An exact retry returns the existing state without consuming quota or creating another approval. Approval bearer tokens are shown only in the original response; after a lost response, continue from the authenticated queue.

Security boundary

  • The API key and tenant boundary are enforced by the Kernel; the model does not decide its own tool permissions.
  • Private arguments remain in your system. CordonRail records their hash plus reviewer-readable, caller-declared material facts.
  • Money movement requires a recorded human decision. Approval and execution authority are distinct, expiring records.
  • An external effect is not treated as reconciled until its outcome is recorded. Pending reconciliation remains visible.
  • Exports distinguish hash consistency, signer provenance, and trusted anchors. A self-consistent file alone is not proof of authentic history.

Known limitations

  • actionSchemaId, integration identity, version, and material facts are caller-declared. The current pilot records and binds them; it does not yet host or validate a tenant schema registry.
  • The free sandbox ceiling is deployment-configured. If the Usage page says it is not configured, no enforced quota is being claimed.
  • Channel notification code is not the same as identity-bound approval inside a chat tool. Do not claim chat approval unless the deployed path has separate evidence.
  • No certification, compliance verdict, unexplained risk score, broad connector catalogue, enterprise SLA, or zero-knowledge proof is included in this pilot.
  • Provider delivery, restore, and hosted adversarial evidence are release-specific deployment gates. Local green tests do not close them.

Data handling

Send only non-secret scalar review facts. Arguments, credentials, provider tokens, customer records, and model prompts belong in your own system—not in a proposal.

CordonRail keeps tenant-scoped governance records, approval state, outcome and reconciliation evidence, and the metadata needed to export and verify that record. Access remains constrained by tenant identity and API scope.

The deployment mode shown inside the product is authoritative for durability. A preview notice, durable-admission state, retention policy, export, deletion record, and cryptographic erasure are different mechanisms; the UI must not collapse them into one promise.

SDK status and pilot support

  • The documented HTTP API is the supported external integration contract for this pilot. It can be used from any language that can make HTTPS requests.
  • The TypeScript package @a2d/governed-sdk is exercised inside the Genesis repository, but it is not yet published as a supported public registry package. Do not depend on an unannounced package name or compatibility promise.
  • Pilot support is monitored Monday–Friday, 09:00–17:00 GMT. Ordinary questions receive a response by the next business day.
  • Blocked actions, suspected tenant-boundary failures, unauthorized execution, credential exposure, or evidence-integrity concerns are acknowledged within four business hours during the monitored window.
  • Use the in-product feedback control and include the action identifier, approximate time, and observed response. Never include API keys, approval tokens, customer content, or private action arguments.

This is a founder-operated pilot support window, not a 24/7 service or uptime SLA.

Pilot terms and support boundary

  • Sandbox access is for development, learning, synthetic testing, and workflow evaluation. It does not authorize commercial production use.
  • Production use, support expectations, data classification, action volume, and commercial terms are agreed separately with each pilot team.
  • No public production price or included production volume is promised by this preview. A written production agreement must identify the permitted action classes and operating boundary before real commercial actions are submitted.
  • The numeric sandbox allowance is shown in Usage when configured. Exhaustion refuses new proposals before recording or authority issuance; protection is never silently removed.
  • This is a controlled pilot, not an enterprise SLA. Report failures privately with the action identifier and observed response; never send credentials or customer content in support messages.
  • Known issues will be investigated with the pilot team, but access does not promise that every integration or workflow will be accepted.
Developer guide · CordonRail