Skip to content

Sensorium Directive v1

Source schema: doc/schemas/sensorium-directive.v1.schema.json

Request envelope addressed to sensorium-core by a consumer module (e.g. Arca, Dator, local agent) invoking an intentional action through a Sensorium connector. Consumers address actions by a public action_id; sensorium-core resolves the action_id through the operator-signed allowlist to a specific connector.

Governing Basis

Project Lineage

Requirements

Stories

Fields

Field Required Shape Description
schema yes const: sensorium-directive.v1 Schema tag for the v1 Sensorium contract.
schema/v yes const: 1 Schema version.
directive/id yes string Opaque identifier assigned by the issuer; recommended to be ULID. Used to correlate the request, its outcome record, and any emitted observations.
directive/issued_at yes string RFC 3339 timestamp at which the issuer produced this directive.
issuer yes object Identity of the invoking party. participant/did:key is the sovereign identity axis; module_id identifies the local module when applicable. At least one of participant/did:key or module_id MUST be present.
idempotency/key no string Optional caller-provided idempotency key. sensorium-core SHOULD use it together with issuer and action_id to make retries of async or retryable directives safe.
action_id yes string Public, operator-allowlisted identifier of the action to perform (dotted notation recommended, e.g. os.process.spawn-read-only). Consumers MUST NOT select connector_id; action_id is the only public addressing handle.
parameters yes object Typed parameters for this action_id. Validated by sensorium-core against the parameter schema held in the allowlist entry for this action_id. MUST NOT carry raw shell strings, raw script bodies, or raw SQL; interpretive surfaces are expressed as script_id references to signed stored artifacts.
evidence/inputs no array Optional input artifacts, passed by reference rather than inline, using the minimal artifact-lane contract from proposal 045.
timing yes object Directive-level timing policy. timing.timeout_ms is the end-to-end deadline enforced by sensorium-core from directive admission through connector dispatch and execution to final outcome recording.
deadline_at no string Optional absolute RFC 3339 deadline propagated by the caller. When present, sensorium-core and the connector MUST enforce the smaller of timing.timeout_ms/max_timeout_ms and the remaining time until deadline_at. This keeps role-module HTTP timeouts, Sensorium outcomes, and connector execution telemetry aligned.
correlation/id no string Optional opaque string threading this directive through a higher-level plan (e.g. an Arca workflow run step, a Dator task dispatch). Preserved in the outcome and in any linked observations.
issuer_delegation no ref: #/$defs/delegationProof Optional proposal-032 DelegationProof authorising a proxy key to sign this directive. If present, signature MUST be produced by issuer_delegation.proxy_key and issuer_delegation.principal_key MUST derive to issuer.participant/did:key. Sensorium v1 accepts only max_chain_depth=0.
signature no ref: #/$defs/ed25519Signature

Definitions

Definition Shape Description
artifactRef object Minimal artifact-lane reference. The artifact itself is stored outside this envelope and is addressed by a content or host-owned blob reference.
delegationProof object Compact DelegationProof from proposal 032. In Sensorium v1 the proof may be present, but sub-delegation chains are not supported; max_chain_depth, when present, MUST be 0. Additional fields are tolerated for open-world forward compatibility; the canonical proof payload verified by implementations is limited to the proposal-032 compact proof fields.
ed25519Signature object Ed25519 signature over the canonical directive payload. issuer_delegation is excluded from the surrounding directive payload and has its own principal_signature.
## Field Semantics

schema

  • Required: yes
  • Shape: const: sensorium-directive.v1

Schema tag for the v1 Sensorium contract.

schema/v

  • Required: yes
  • Shape: const: 1

Schema version.

directive/id

  • Required: yes
  • Shape: string

Opaque identifier assigned by the issuer; recommended to be ULID. Used to correlate the request, its outcome record, and any emitted observations.

directive/issued_at

  • Required: yes
  • Shape: string

RFC 3339 timestamp at which the issuer produced this directive.

issuer

  • Required: yes
  • Shape: object

Identity of the invoking party. participant/did:key is the sovereign identity axis; module_id identifies the local module when applicable. At least one of participant/did:key or module_id MUST be present.

idempotency/key

  • Required: no
  • Shape: string

Optional caller-provided idempotency key. sensorium-core SHOULD use it together with issuer and action_id to make retries of async or retryable directives safe.

action_id

  • Required: yes
  • Shape: string

Public, operator-allowlisted identifier of the action to perform (dotted notation recommended, e.g. os.process.spawn-read-only). Consumers MUST NOT select connector_id; action_id is the only public addressing handle.

parameters

  • Required: yes
  • Shape: object

Typed parameters for this action_id. Validated by sensorium-core against the parameter schema held in the allowlist entry for this action_id. MUST NOT carry raw shell strings, raw script bodies, or raw SQL; interpretive surfaces are expressed as script_id references to signed stored artifacts.

evidence/inputs

  • Required: no
  • Shape: array

Optional input artifacts, passed by reference rather than inline, using the minimal artifact-lane contract from proposal 045.

timing

  • Required: yes
  • Shape: object

Directive-level timing policy. timing.timeout_ms is the end-to-end deadline enforced by sensorium-core from directive admission through connector dispatch and execution to final outcome recording.

deadline_at

  • Required: no
  • Shape: string

Optional absolute RFC 3339 deadline propagated by the caller. When present, sensorium-core and the connector MUST enforce the smaller of timing.timeout_ms/max_timeout_ms and the remaining time until deadline_at. This keeps role-module HTTP timeouts, Sensorium outcomes, and connector execution telemetry aligned.

correlation/id

  • Required: no
  • Shape: string

Optional opaque string threading this directive through a higher-level plan (e.g. an Arca workflow run step, a Dator task dispatch). Preserved in the outcome and in any linked observations.

issuer_delegation

  • Required: no
  • Shape: ref: #/$defs/delegationProof

Optional proposal-032 DelegationProof authorising a proxy key to sign this directive. If present, signature MUST be produced by issuer_delegation.proxy_key and issuer_delegation.principal_key MUST derive to issuer.participant/did:key. Sensorium v1 accepts only max_chain_depth=0.

signature

  • Required: no
  • Shape: ref: #/$defs/ed25519Signature

Definition Semantics

$defs.artifactRef

  • Shape: object

Minimal artifact-lane reference. The artifact itself is stored outside this envelope and is addressed by a content or host-owned blob reference.

$defs.delegationProof

  • Shape: object

Compact DelegationProof from proposal 032. In Sensorium v1 the proof may be present, but sub-delegation chains are not supported; max_chain_depth, when present, MUST be 0. Additional fields are tolerated for open-world forward compatibility; the canonical proof payload verified by implementations is limited to the proposal-032 compact proof fields.

$defs.ed25519Signature

  • Shape: object

Ed25519 signature over the canonical directive payload. issuer_delegation is excluded from the surrounding directive payload and has its own principal_signature.