Skip to content

outputs.md

Latest commit

 

History

History
85 lines (50 loc) · 6.51 KB

outputs.md

File metadata and controls

85 lines (50 loc) · 6.51 KB
Raw

Outputs

What a session produces on close (v0.3).

Identity fields on export: trust-paths.md. Session-close workflow: using-aura.md.

Per session

Artifact Path Contents
Audit trail {session_id}.jsonl Append-only AuraEvents with causal ids + hash chain
Summary {session_id}.summary.json Metadata, conformance, audit report
OTel JSONL {session_id}.otel.jsonl Span-style records mapped from events; written on close by default and refreshed by aura export-otel

CLI: aura report show <session_id>, aura report show <session_id> --json, aura export, aura export-otel, aura compare, aura verify chain <path>.

Export commit: Summary and OTel files are written to staging paths and renamed atomically on success. If export fails, neither artifact is committed (the live JSONL trail may still exist from the session). With export=False, the SDK still builds run.summary and run.audit_report in memory.

Closed session: After close, emit, approve, and a second close() raise SessionClosedError. session_id and trace_id are fixed at open. open_snapshot_hash captures rules + sequencer at open for conformance; snapshot_hash in the summary may update when skills bind at runtime.

Spine events (identity): When an operator adapter binds, the session emits identity.bound after session.open. Operator fields appear under agent_ids.ids.operator on subsequent events. JSONL retains full fields; summary and OTel apply redaction defaults.

Spine events (escalation): When profile.escalations[] is set, trigger events (slo.missed, conformance.drift, observer.alert, constraint.violated) may emit escalation.fired and action events (membrane.nudge, escalation.email, escalation.wake). See observers.md.

Spine events (spectrum): session.open and membrane.ingress carry a spectrum summary when the profile has a spectrum block. session.open also includes services_activation — which presets wired at open (activated, skipped_explicit, unknown) — and verified_identity_required + source when the verified-ID gate applies (#73). See aura-levels.md.

Spine events (capabilities): When profile.capabilities[] is set, session.open spectrum summary includes a capabilities block (count, ids, gated_tools, secret_refs, broker kind). Scope misses emit constraint.violated (with audit_only at spectrum low). constraint.passed lists only rules that passed. Successful inject emits capability.injected (capability id + secret refs and targets in injected[], never values; #86). Secret-like payload keys (token, api_key, …) are redacted on every emit, including sessions without capabilities. Findings: CAPABILITY_DENIED, CAPABILITY_AUDIT, SECRET_BROKER_ERROR. See capabilities.md.

Spine events (schema): When variables.schema_refs or schema_check rules are active, session.open spectrum summary includes a schema block (refs, active_rules, auto_enforced). Malformed tool.call args or tool.result payloads emit constraint.violated. Audit finding: SCHEMA_VIOLATION. Conformance includes a schema check on close. See aura-levels.md.

Spine events (middleware & PII masking): When sequencer steps or boundaries execute middleware (e.g. middleware.pii_mask #58), the session emits middleware.applied containing detection counts (entities_detected), total redactions, strategy (redact, mask, pseudonymize), and modified fields. Raw PII is strictly forbidden from the spine. Audit scorecard records scorecard.middleware = {"applied": count, "pii_redactions": count} and surfaces finding PII_MASKED (severity: info). See sequencer.md.

Spine events (break preset & observer alerts): When observer presets (such as break #93) detect runaway cycles or repetition, the session emits observer.alert containing pattern (ACTION_FIXATION, OSCILLATION_CYCLE, CHOREOGRAPHY_CYCLE, ERROR_STATUS_CHURN, REASONING_INERTIA), structured remedial_directive, and non-repudiable cryptographic hashes (cycle_entry_hash, cycle_recurrence_hash). Audit scorecard records scorecard.observers = {"alerts": count, "loop_cycles": count} and surfaces finding COGNITIVE_CYCLE_DETECTED (severity: warn). See observers.md.

Audit report (summary JSON)

{
  "verdict": "pass",
  "scorecard": { "policy": {}, "tools": {}, "sequencer": {}, "events": 12 },
  "findings": [],
  "recommendations": ["..."],
  "hash_chain_valid": true
}

Rule-based today — findings cite event_ids; recommendations suggest next steps (policy, sequencer, approvals).

Use aura report show for a human-readable audit report from the session summary JSON, or add --json for CI and other machine consumers. See using-aura.md for the complete session-close workflow.

Conformance

Binary pass/fail plus violations list — declared rules, sequencer step order, goal/SLO drift, and schema rule violations vs observed spine.

Hash chain

Each event includes prev_hash and content_hash (SHA-256). Tampering or corruption breaks verification in the audit report.

Use aura verify chain <path> to validate an exported JSONL audit trail directly. It prints a JSON object with hash_chain_valid; when the chain is broken, the object also identifies the first affected event_id and the command exits with status 1.

Identity on exports

Summary includes agent_ref, aura_id, policy_version, snapshot_hash, and full agent_ids trailer.

OTel spans

aura export-otel writes {session_id}.otel.jsonl. Spans inherit promoted attributes where available:

  • aura.agent_ref, aura.policy_version — session identity
  • aura.principal — approver on gated calls
  • aura.operator.subject, aura.operator.method, aura.operator.verified — session operator when identity adapter bound
  • aura.skill_id — skill on tool and registration events

→ trust-paths.md · aura-event.schema.json · reference-tool-host-capstone.md