# ZeroExternal operation profile v1 — offline reference SDK

`zeroexternal.operation.v1` is an illustrative, proposed application profile carried in a CloudEvents 1.0 structured JSON event. It is a concrete common contract for describing submitted operation requests across 13 scenarios. It is not an industry standard, a claim of adoption, or an authenticated control plane.

The envelope records that a request was submitted. Receiving it does not authorize or execute the request. `capability_ref` is an opaque lookup reference, never a capability grant, signature, or proof. The reverse-DNS event type and other names confer no authority. Validation reports `authorization: "not_evaluated"`. The offline evaluator can report `allow`, but every result also reports `simulation_only: true` and `authoritative: false`.

No existing runtime is made to accept this envelope by these files. Existing native APIs remain the integration contract until a separately implemented, tested adapter bridge maps the profile to them. These files do not send requests, execute work, control devices, transfer money, or settle accounts.

## Files and quick start

- `core.mjs`: self-contained JavaScript ES module for browsers or Node; no imports or dependencies.
- `operation_profile.py`: self-contained Python 3 module and bounded file checker; standard library only.
- `operation.schema.json`: JSON Schema Draft 2020-12 contract for shape and field constraints.
- `examples/*.json`: one operation for each supported scenario.
- `policy.example.json`: separately supplied illustrative policy input.
- `conformance-vectors.json`: 20 golden vectors with exact expected validation and policy outputs.
- `conformance.py`, `conformance.mjs`: offline conformance runners.

```sh
python operation_profile.py check examples/science.json
python conformance.py                 # Python checks and exact JavaScript result parity; Node required
python conformance.py --python-only   # Python only
node conformance.mjs                  # JavaScript only
```

Run from this directory. `check` exits 0 for valid shape, 1 for invalid input, and 2 for incorrect CLI arguments. It prints the result and performs no operation. `conformance.py` invokes local Node only to compare results.

```js
import { makeExample, makeExamplePolicy, validateOperation, evaluatePolicy } from './core.mjs';
const request = makeExample('robotics');
const validation = validateOperation(request);
const policy = makeExamplePolicy(request); // fixture, not a policy issued by an authority
const simulation = evaluatePolicy(request, policy, '2026-09-26T12:30:00Z');
```

```python
from operation_profile import makeExample, makeExamplePolicy, validateOperation, evaluatePolicy
request = makeExample('science')
validation = validateOperation(request)
simulation = evaluatePolicy(request, makeExamplePolicy(request), '2026-09-26T12:30:00Z')
```

## Stable envelope and API

The event requires exactly `specversion`, `id`, `source`, `type`, `subject`, `time`, `datacontenttype`, and `data`. This profile deliberately narrows CloudEvents: UUID event IDs, an absolute HTTPS/URN URI subset, a required subject and UTC timestamp, JSON data, and no extension attributes. CloudEvents itself allows broader values and optional metadata. The fixed type is `ai.zeroexternal.operation.requested.v1`, and the media type of the payload is `application/json`. A transport using structured CloudEvents JSON should use the outer event media type `application/cloudevents+json`; this SDK supplies no transport.

`data` contains exactly:

| Field | Meaning |
|---|---|
| `profile` | Fixed `zeroexternal.operation.v1` version identifier |
| `operation_id` | UUID of the described operation |
| `scenario_id` | One supported scenario identifier |
| `actor` | Claimed `id`, `kind`, and `owner_id`; identity is not authenticated here |
| `intent` | Action, target, nonnegative integer `expected_revision`, and domain `parameters` |
| `capability_ref` | Opaque reference to resolve through an independent trusted policy service |
| `budget` | Declared unit and nonnegative integer maximum |
| `idempotency_key` | Declared retry key; this stateless SDK stores no deduplication state |
| `evidence_required` | Requested evidence categories; their presence and truth are not checked here |
| `acceptance` | Named reviewer and requested criteria; no acceptance is performed |
| `settlement` | `none` or `separate_acceptance`; `automatic` must be `false` |

`validateOperation(value)` returns `{valid, errors: [{path, code}], authorization: "not_evaluated"}`. Errors use JSON Pointer paths and deterministic ordering. Inputs are decoded plain JSON values. Python additionally exposes `validate_operation` as an alias.

`evaluatePolicy(operation, policy, now)` returns `{decision: "allow" | "deny", reasons: [string], simulation_only: true, authoritative: false}`. `now` must be provided explicitly as a supported UTC timestamp. The function first checks the operation, policy shape, and clock. It then compares the capability reference, actor ID, action, target, revision, scenario and budget unit, requires `now < expires_at`, and requires the declared maximum not to exceed the policy limit. It does not inspect the domain parameters. Python also exposes `evaluate_policy`.

The separately supplied policy requires exactly:

```json
{
  "reference": "capability:example-reference",
  "actor_id": "actor:example",
  "action": "propose_experiment",
  "target": "science/task-001",
  "expected_revision": 1,
  "expires_at": "2026-09-26T13:00:00Z",
  "budget": {"unit": "review_units", "limit": 10},
  "scenario_id": "science"
}
```

This fixture illustrates a trusted-policy *input boundary*. Authenticating the caller, securely loading an issued policy, binding an actor to an owner, checking revocation, current revision and available funds, atomic budget reservation, recording idempotency, validating evidence and checking reviewer authority remain the responsibility of an actual authority and adapter. Copying a reference or changing a client policy object cannot grant permission in a real integration. The local evaluator does not attest to any of those guarantees.

## Bounded input and schema scope

Unknown contract and policy fields are rejected. Domain `parameters` remain uninterpreted bounded JSON; the owning domain adapter must validate their schema, units, target semantics and safety rules before any effect. Clinical decisions, physical motion and financial transfers require their own actual controls and are not implemented by a generic envelope.

Runtime limits are 12 nesting levels (root depth 0), 512 values, 64 entries per object or array, 2,048 Unicode code points per string, 64 code points per property name, and 16,384 cumulative UTF-8 bytes across strings and property names. `__proto__`, `constructor`, and `prototype` property names, cycles, non-JSON values, unpaired surrogates, nonfinite numbers and numbers outside ±(2^53−1) are rejected. Budget amounts and revisions are integers in [0, 1,000,000,000]. IDs and references use bounded ASCII identifier characters. Fractional timestamps allow 1–3 digits; years start at 0001 and leap seconds are excluded. Calendar validity is checked. Source URIs deliberately exclude ports, queries, fragments and percent escapes in this first profile.

`parseOperationJSON(text)` rejects duplicate object keys and adds a 32,768-byte raw input limit and returns `{operation, validation}`. The Python file checker also limits bytes before decoding. Parse raw untrusted JSON through a bounded ingress; never pass executable JavaScript objects, accessors or proxies as data. Neither implementation fetches a schema or resolves a capability reference.

The JSON Schema includes field limits but cannot express the aggregate byte/node/depth budget; the portable validators enforce those additional profile rules. External Draft 2020-12 validators must actively assert date/time and URI formats, which may otherwise be annotation-only. Use this SDK plus its conformance vectors for this profile rather than interpreting a schema-only success as complete profile conformance. These validators implement this fixed schema's vocabulary subset; they are not general JSON Schema engines.

Examples have fixed, scenario-distinct identifiers for reproducibility. A producer must generate fresh event IDs for distinct real occurrences and implement its own durable idempotency behavior.

## Scenario ownership

Supported scenarios are `science`, `agents`, `people`, `robotics`, `payments`, `supply-chain`, `healthcare`, `manufacturing`, `agriculture`, `real-estate`, `creative`, `enterprise`, and `custom`. Their examples use proposal actions and review units. Scenario names are a catalog for this prototype, not proof of a deployed adapter or sector endorsement. Each scenario can share the operation fields while its owner implements the domain adapter and its actual policy/evidence checks.

## Primary references

Verified 2026-09-26:

- [CloudEvents specification v1.0.2](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md): metadata and event-data model; the serialized `specversion` is `1.0`.
- [CloudEvents JSON event format v1.0.2](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/formats/json-format.md): structured JSON serialization.
- [JSON Schema Draft 2020-12 validation](https://json-schema.org/draft/2020-12/json-schema-validation): structural assertions and format behavior.
- [JSON Schema object reference](https://json-schema.org/understanding-json-schema/reference/object): closed objects with `additionalProperties: false`.

CloudEvents and JSON Schema provide established building blocks. The proposed ZeroExternal application semantics and offline policy evaluation above are specific to this prototype.