Jira progress: loading…

ZCP-API

API ⇄ ZCP Translation Spec

1. Purpose

This specification defines how external and internal API requests are translated into ZCP commands, and how ZCP execution results are translated back into API responses.

It establishes the bridge between:

REST or HTTP-based API surfaces
ZCP semantic command execution
opcode-based runtime intent
ZSSR-governed routing and validation
CMI/CSI-based artifact and signal identity

Its goal is to ensure that:

APIs remain developer-friendly
ZCP remains the canonical internal execution protocol
routing, governance, and semantic intent are not duplicated across parallel systems
the same semantic action can be exposed through multiple API surfaces without changing the underlying execution model

2. Core principle

APIs are exposure surfaces. ZCP is the internal execution language.

That means:

APIs should not be the ultimate source of execution semantics
operation_key and opcode define semantic intent
API routes should translate into ZCP commands
runtime execution should happen through ZCP + ZSSR + approved manifest metadata
API responses should be projections of ZCP execution outcomes

So the architecture is:

API request → Translation Layer → ZCP Command → ZSSR Routing → Artifact Execution → ZCP Result → API response

3. Why this matters

Without this translation layer, the platform risks:

REST routes becoming the de facto logic layer
duplicated routing logic
duplicated policy enforcement
inconsistent engine behavior across API surfaces
harder future support for non-HTTP channels

With this layer, ZAYAZ can later support:

REST APIs
internal service calls
async jobs
event-driven invocations
agent invocations
geographic optimization
self-optimizing routing

without redefining execution semantics each time.

4. Scope

This specification covers:

inbound API to ZCP translation
outbound ZCP to API translation
use of opcode, operation_key, CMI, CSI, ruleset profile, and ZSSR flags
error mapping
idempotency mapping
response shaping
policy and routing implications

This spec does not yet define:

geographic optimization
client-local execution
self-optimizing routing
multi-region dynamic execution policy

Those come later as an extension layer.

5. Translation architecture overview

5.1. Inbound path

A client sends:

HTTP method
route/path
headers
auth context
query params
body/payload

The translation layer resolves:

API route binding
operation_key
opcode
artifact type and/or target CMI resolution strategy
CSI input/output contract expectations
execution mode
ruleset profile
ZSSR requirement
policy defaults
ZCP command envelope

Then ZCP executes through governed runtime routing.

5.2. Outbound path

The runtime returns:

execution status
opcode result
output signals / payload
lineage / trace metadata
warnings/errors
trust/governance metadata if needed

The translation layer converts this into:

HTTP status code
response body
headers
optional async job metadata
error object shape
pagination/result metadata if relevant

6. Design principles

6.1. Semantic-first

The translation layer must resolve semantic intent first, not transport mechanics first.

6.2. Deterministic-first

Route-to-opcode mapping should be deterministic wherever possible.

6.3. Manifest-backed

Translation should prefer approved canonical manifest data, not ad hoc route logic.

6.4. Governance-preserving

API translation must not bypass:

ZSSR
rulesets
review constraints
trust thresholds
artifact compatibility checks

6.5. Channel-neutral execution

Different API shapes may map to the same opcode and same ZCP command semantics.

7. Core translation entities

The translation layer depends on these entity types.

7.1. API Route Binding

A mapping from an API route/method pair to semantic execution intent.

Minimum fields:

route template
HTTP method
operation_key
opcode
artifact type
target resolution mode
input contract mapping
output contract mapping
ruleset profile hint
public exposure policy
requires_zssr
execution mode

7.2. ZCP Command Envelope

Canonical runtime execution payload.

7.3. ZCP Result Envelope

Canonical runtime execution result payload.

7.4. Translation Policy

Rules for:

idempotency
error mapping
auth-to-policy mapping
sync/async behavior
response projection

8. Required translation inputs

For inbound translation, the system should consider:

HTTP method
path
route params
query params
request body
auth context
tenant/client context
environment scope
API version
optional preferred response shape

And registry/governance context:

opcode registry
artifact-type binding
ruleset profile binding
approved manifests
CMI and CSI bindings
ZSSR policy

9. Inbound translation stages

Stage 1 — Resolve API route binding

Given:

method
path

Resolve:

route binding record
operation_key
opcode
translation profile

Example:

POST /api/v1/exports/xbrl
→ operation_key = export_xbrl
→ opcode = OP_0910
→ artifact_type = exporter
→ requires_zssr = true
→ execution_mode = hybrid

If no binding exists:

reject request
return API-level route-not-mapped error
do not attempt semantic guessing in production

Stage 2 — Resolve target artifact

Depending on binding strategy, the translation layer may resolve:

explicit CMI

The route binding directly points to a known CMI.

artifact family / type

The route binding only declares artifact type, and runtime resolution chooses the concrete artifact.

manifest-backed capability resolution

The route binding points to operation_key/opcode, and runtime resolves the target through approved manifest data and compatibility tables.

This stage should validate:

opcode exists
artifact type is compatible
target is active/allowed
environment permits execution

Stage 3 — Map API input to canonical ZCP input

This stage converts:

route params
query params
body fields
headers/context

into:

canonical input structure
CSI-linked payload shape where applicable
metadata fields
execution context

This mapping can be:

direct field mapping
contract/schema transformation
CSI-aware input translation

Stage 4 — Attach execution policy

The translation layer should attach:

requires_zssr
ruleset profile candidate
audit requirement
review requirements
retention class
trust threshold
execution mode
idempotency policy

These should be inherited from:

opcode registry
artifact-type binding
ruleset profile binding
approved manifest overrides

Stage 5 — Build ZCP command envelope

The translation layer then emits a canonical ZCP command.

Example shape:

zcp-command-envelope.yamlGitHub ↗
zcp_version: "0.1"
command_id: "cmd_01J..."
operation_key: "export_xbrl"
opcode: "OP_0910"

target:
  artifact_type: "exporter"
  cmi: "mice.EXPORT.EXPORTER.XBRL_EXPORT.1_0_0"

context:
  invoked_via: "api"
  api_method: "POST"
  api_route: "/api/v1/exports/xbrl"
  environment_scope: "production"
  tenant_id: "tenant_123"

routing:
  via_zssr: true
  ruleset_profile_code: "XBRL_EXPORT_DEFAULT"

input:
  contract_type: "report_package"
  payload:
    report_id: "RPT-0001"
    taxonomy: "ESRS"
    format_version: "2026"

policy:
  audit_required: true
  human_review_required: false
  retention_class: "compliance_7y"
  min_trust_score: 0.92

trace:
  source_binding_id: "api_binding_..."
  source_manifest_id: "manifest_..."

10. Outbound translation stages

Stage 1 — Receive ZCP result

ZCP runtime should return a result envelope such as:

outbound-translation-stages.yamlGitHub ↗
zcp_version: "0.1"
command_id: "cmd_01J..."
status: "success"

opcode: "OP_0910"
operation_key: "export_xbrl"

output:
  contract_type: "disclosure_artifact"
  payload:
    artifact_id: "ART-0009"
    storage_url: "..."
    checksum: "..."

warnings: []
errors: []

trace:
  execution_id: "exec_..."
  route_id: "..."
  resolved_cmi: "..."

Stage 2 — Map result to API response shape

The translation layer converts:

status
output.contract_type
output.payload
warnings/errors
trace metadata

into:

HTTP status code
response JSON
optional headers
async tracking metadata

11. API response mapping rules

11.1. Success mapping

Recommended defaults:

success → 200 OK
accepted_async → 202 Accepted
created_artifact → 201 Created where appropriate

11.2. Validation failure

If request failed validation before or during ZSSR:

map to 400 Bad Request or 422 Unprocessable Entity

11.3. Authorization / policy denial

If blocked by policy, exposure, or capability:

403 Forbidden

11.4. Route binding / capability not found

If route exists but no valid semantic binding/target:

404 Not Found or 409 Conflict, depending on semantics

11.5. Internal execution failure

If execution failed after valid translation:

500 Internal Server Error or domain-specific error mapping

12. Example translation mappings

Example 1 — Export XBRL

API request

example-export-xbrl.httpGitHub ↗
POST /api/v1/exports/xbrl
Content-Type: application/json
Authorization: Bearer ...

{
  "report_id": "RPT-0001",
  "taxonomy": "ESRS",
  "format_version": "2026"
}

Translation result

operation_key = export_xbrl
opcode = OP_0910
artifact_type = exporter
input_contract_type = report_package
via_zssr = true
ruleset profile = XBRL_EXPORT_DEFAULT

ZCP execution

OP_0910 invoked on approved exporter target.

API response

zcp-execution-response.jsonGitHub ↗
{
  "status": "success",
  "artifact_id": "ART-0009",
  "execution_id": "exec_01J..."
}

Example 2 — Compute metric

API request

example-compute-metric.httpGitHub ↗
POST /api/v1/metrics/compute
{
  "metric_key": "scope_2_market_based",
  "inputs": {
    "electricity_kwh": 140000,
    "market_factor": 0.012
  }
}

Translation result

operation_key = compute_metric
opcode = OP_0600
artifact_type = micro_engine or engine
input CSI set resolved from metric profile
ruleset profile = metric-specific compute profile

ZCP execution

ZSSR resolves the most appropriate approved computation artifact.

Example 3 — Review request

API request

example-review-request.httpGitHub ↗
POST /api/v1/reviews/request
{
  "artifact_id": "manifest_123",
  "reason": "ambiguous csi mapping"
}

Translation result

operation_key = request_human_review
opcode = OP_0810
governance-sensitive
internal-only or privileged API
human-review workflow dispatch required

13. Recommended route binding schema

You will likely need a registry table or manifest structure for this.

Recommended logical fields:

api_binding_id
route_template
http_method
api_version
operation_key
opcode
artifact_type
target_resolution_mode
target_cmi nullable
input_contract_type
output_contract_type
request_mapping_profile
response_mapping_profile
ruleset_profile_code nullable
requires_zssr
public_api_allowed
execution_mode
status
manifest_id or source_manifest_id
created_at
updated_at

This will be the:

zar.api_route_binding_registry

14. Translation policy rules

Rule 1

API bindings must resolve to approved semantic intent.

Rule 2

API route translation must not bypass opcode compatibility checks.

Rule 3

If requires_zssr = true, the request must always route through ZSSR.

Rule 4

Ruleset-specific variants should prefer ruleset profile bindings, not new opcodes.

Rule 5

If a public API route maps to an opcode whose binding is internal-only, reject exposure.

Rule 6

Translation must be auditable and reproducible.

15. Idempotency handling

The translation layer should map opcode idempotency semantics into API behavior.

If idempotency_default = true

support idempotency key headers where relevant
safe retries allowed

If idempotency_default = false

API route should avoid accidental replay
translation layer may require special replay controls
async job model may be preferred

16. Async vs sync handling

If the resolved execution mode is:

sync

Wait for ZCP result and return direct API response.

async

Return:

202 Accepted
job/command ID
tracking endpoint reference

hybrid

Translation layer may:

respond synchronously for short runtime
degrade to async if thresholds exceeded

17. Security and governance

The translation layer must preserve:

auth context
tenant/client context
exposure controls
policy restrictions
governance sensitivity
lineage / trace data

It should never strip away the information needed for:

audit
replay
policy review
incident diagnosis

18. Traceability requirements

Each translation event should ideally produce traceable metadata:

inbound request id
resolved route binding id
resolved opcode
resolved operation_key
resolved artifact target
ruleset profile used
command_id
execution_id
response mapping profile used

This is critical for ZAYAZ because it enables:

governance evidence
runtime diagnostics
future self-optimization
later geo-aware or client-aware routing intelligence

19. Translation failure classes

Recommended classes:

route_binding_not_found
opcode_not_found
artifact_type_incompatible
target_resolution_failed
ruleset_profile_missing
zssr_policy_denied
input_mapping_invalid
output_mapping_invalid
execution_failed

These should later map to standard API error envelopes.

20. Strategic extension path

This translation layer becomes the perfect insertion point for:

location-aware target selection
client-local optimization
latency-aware routing
cost-aware execution
policy-aware regional routing
self-optimizing engine selection
dynamic artifact ranking

That should be implemented as translation/routing policy extensions, not by changing opcode semantics.

That distinction is important.

Seed examples for zar.api_route_binding_registry

seed-example-api-route-binding-registry.sqlGitHub ↗
INSERT INTO zar.api_route_binding_registry (
    api_binding_id,
    route_template,
    http_method,
    api_version,
    binding_name,
    description,
    operation_key,
    opcode,
    artifact_type,
    target_resolution_mode,
    target_cmi,
    target_cmi_version,
    input_contract_type,
    output_contract_type,
    request_mapping_profile,
    response_mapping_profile,
    ruleset_profile_code,
    requires_zssr,
    public_api_allowed,
    partner_api_allowed,
    internal_api_allowed,
    execution_mode,
    idempotency_supported,
    auth_profile_code,
    tenant_scope_mode,
    route_params_schema,
    query_params_schema,
    request_body_schema,
    response_body_schema,
    fixed_context,
    default_input_payload,
    source_manifest_id,
    source_manifest_ref,
    source_notes,
    status,
    lifecycle_status,
    version,
    sort_order
) VALUES

(
    'api.exports.xbrl.post.v1',
    '/api/v1/exports/xbrl',
    'POST',
    'v1',
    'Export XBRL',
    'Maps XBRL export requests to the canonical XBRL export opcode.',
    'export_xbrl',
    'OP_0910',
    'exporter',
    'manifest_capability',
    NULL,
    NULL,
    'report_package',
    'disclosure_artifact',
    'xbrl_export_request_v1',
    'xbrl_export_response_v1',
    'XBRL_EXPORT_DEFAULT',
    TRUE,
    TRUE,
    TRUE,
    TRUE,
    'hybrid',
    TRUE,
    'bearer_tenant_user_v1',
    'caller_scoped',
    '{}'::jsonb,
    '{}'::jsonb,
    '{"type":"object","required":["report_id","taxonomy","format_version"]}'::jsonb,
    '{"type":"object"}'::jsonb,
    '{"invoked_via":"api"}'::jsonb,
    '{"export_type":"xbrl"}'::jsonb,
    NULL,
    NULL,
    NULL,
    'active',
    'active',
    '1_0_0',
    100
),

(
    'api.metrics.compute.post.v1',
    '/api/v1/metrics/compute',
    'POST',
    'v1',
    'Compute Metric',
    'Maps metric computation requests to the canonical compute metric opcode.',
    'compute_metric',
    'OP_0600',
    'micro_engine',
    'manifest_capability',
    NULL,
    NULL,
    'signal_set',
    'signal_set',
    'metric_compute_request_v1',
    'metric_compute_response_v1',
    'METRIC_COMPUTE_DEFAULT',
    TRUE,
    TRUE,
    TRUE,
    TRUE,
    'sync',
    TRUE,
    'bearer_tenant_user_v1',
    'caller_scoped',
    '{}'::jsonb,
    '{}'::jsonb,
    '{"type":"object","required":["metric_key","inputs"]}'::jsonb,
    '{"type":"object"}'::jsonb,
    '{"invoked_via":"api"}'::jsonb,
    '{}'::jsonb,
    NULL,
    NULL,
    NULL,
    'active',
    'active',
    '1_0_0',
    110
),

(
    'api.reports.quarterly.pull.post.v1',
    '/api/v1/reports/quarterly/pull',
    'POST',
    'v1',
    'Pull Quarterly Report',
    'Maps quarterly report pull requests to the canonical external pull opcode.',
    'pull_from_external_system',
    'OP_1410',
    'connector',
    'manifest_capability',
    NULL,
    NULL,
    'external_pull_request',
    'external_pull_result',
    'quarterly_report_pull_request_v1',
    'quarterly_report_pull_response_v1',
    'QREPORT_PULL_DEFAULT',
    TRUE,
    FALSE,
    TRUE,
    TRUE,
    'async',
    TRUE,
    'partner_bearer_v1',
    'caller_scoped',
    '{}'::jsonb,
    '{}'::jsonb,
    '{"type":"object","required":["client_code","report_type"]}'::jsonb,
    '{"type":"object"}'::jsonb,
    '{"invoked_via":"api"}'::jsonb,
    '{"latest":true}'::jsonb,
    NULL,
    NULL,
    NULL,
    'active',
    'active',
    '1_0_0',
    120
),

(
    'api.reviews.request.post.v1',
    '/api/v1/reviews/request',
    'POST',
    'v1',
    'Request Human Review',
    'Maps review request submissions to the canonical human review opcode.',
    'request_human_review',
    'OP_0810',
    'workflow_dispatcher',
    'workflow_template',
    NULL,
    NULL,
    'review_request',
    'review_request_result',
    'review_request_v1',
    'review_request_response_v1',
    'HUMAN_REVIEW_DEFAULT',
    TRUE,
    FALSE,
    FALSE,
    TRUE,
    'async',
    FALSE,
    'bearer_internal_user_v1',
    'caller_scoped',
    '{}'::jsonb,
    '{}'::jsonb,
    '{"type":"object","required":["artifact_id","reason"]}'::jsonb,
    '{"type":"object"}'::jsonb,
    '{"invoked_via":"api"}'::jsonb,
    '{}'::jsonb,
    NULL,
    NULL,
    NULL,
    'active',
    'active',
    '1_0_0',
    130
),

(
    'api.workflows.dispatch.post.v1',
    '/api/v1/workflows/dispatch',
    'POST',
    'v1',
    'Dispatch Workflow',
    'Maps workflow dispatch requests to the canonical workflow dispatch opcode.',
    'dispatch_workflow',
    'OP_0800',
    'workflow_dispatcher',
    'manifest_capability',
    NULL,
    NULL,
    'workflow_request',
    'workflow_result',
    'workflow_dispatch_request_v1',
    'workflow_dispatch_response_v1',
    'WORKFLOW_DISPATCH_DEFAULT',
    TRUE,
    FALSE,
    TRUE,
    TRUE,
    'async',
    TRUE,
    'bearer_internal_user_v1',
    'caller_scoped',
    '{}'::jsonb,
    '{}'::jsonb,
    '{"type":"object","required":["workflow_key","payload"]}'::jsonb,
    '{"type":"object"}'::jsonb,
    '{"invoked_via":"api"}'::jsonb,
    '{}'::jsonb,
    NULL,
    NULL,
    NULL,
    'active',
    'active',
    '1_0_0',
    140
);

Example bindings

Route bindings

api_binding_id	route_template	http_method	operation_key	opcode	artifact_type	target_resolution_mode	status
`api.exports.xbrl.post.v1`	`/api/v1/exports/xbrl`	POST	`	`OP_0910`	`exporter`	`manifest_capability`	active
`api.metrics.compute.post.v1`	`/api/v1/metrics/compute`	POST	`	`OP_0600`	`micro_engine`	`manifest_capability`	active
`api.reports.quarterly.pull.post.v1`	`/api/v1/reports/quarterly/pull`	POST	`	`OP_1410`	`connector`	`manifest_capability`	active
`api.reviews.request.post.v1`	`/api/v1/reviews/request`	POST	`	`OP_0810`	`workflow_dispatcher`	`workflow_template`	active
`api.workflows.dispatch.post.v1`	`/api/v1/workflows/dispatch`	POST	`	`OP_0800`	`workflow_dispatcher`	`manifest_capability`	active
`

GitHub Repo Request for Change (RFC)

1. Purpose​

2. Core principle​

3. Why this matters​

4. Scope​

5. Translation architecture overview​

5.1. Inbound path​

5.2. Outbound path​

6. Design principles​

6.1. Semantic-first​

6.2. Deterministic-first​

6.3. Manifest-backed​

6.4. Governance-preserving​

6.5. Channel-neutral execution​

7. Core translation entities​

7.1. API Route Binding​

7.2. ZCP Command Envelope​

7.3. ZCP Result Envelope​

7.4. Translation Policy​

8. Required translation inputs​

9. Inbound translation stages​

10. Outbound translation stages​

11. API response mapping rules​

11.1. Success mapping​

11.2. Validation failure​

11.3. Authorization / policy denial​

11.4. Route binding / capability not found​

11.5. Internal execution failure​

12. Example translation mappings​

13. Recommended route binding schema​

14. Translation policy rules​

15. Idempotency handling​

16. Async vs sync handling​

17. Security and governance​

18. Traceability requirements​

19. Translation failure classes​

20. Strategic extension path​

Seed examples for zar.api_route_binding_registry​

Example bindings​

1. Purpose

2. Core principle

3. Why this matters

4. Scope

5. Translation architecture overview

5.1. Inbound path

5.2. Outbound path

6. Design principles

6.1. Semantic-first

6.2. Deterministic-first

6.3. Manifest-backed

6.4. Governance-preserving

6.5. Channel-neutral execution

7. Core translation entities

7.1. API Route Binding

7.2. ZCP Command Envelope

7.3. ZCP Result Envelope

7.4. Translation Policy

8. Required translation inputs

9. Inbound translation stages

10. Outbound translation stages

11. API response mapping rules

11.1. Success mapping

11.2. Validation failure

11.3. Authorization / policy denial

11.4. Route binding / capability not found

11.5. Internal execution failure

12. Example translation mappings

13. Recommended route binding schema

14. Translation policy rules

15. Idempotency handling

16. Async vs sync handling

17. Security and governance

18. Traceability requirements

19. Translation failure classes

20. Strategic extension path

Seed examples for zar.api_route_binding_registry

Example bindings