queue-record-schema.md

Queue Record Schema And Read-Only Projection Contract

Status: [preview/bounded] TASK-0053 schema artifact; queue implementation remains blocked until future bounded tasks are approved. Capability label: [preview/bounded] queue / runtime records are disabled by default; schema reserved. Depends on: docs/archive/task-reports/daemon-queue-implementation-split.md Boundary ADR: docs/adr/0002-v2-daemon-and-execution-boundary.md Credential boundary: docs/adr/0003-credential-handling-boundary.md Hosted and marketplace boundary: docs/adr/0004-hosted-integration-and-marketplace-boundary.md Permission model: docs/reference/execution-permission-model.md Runner recovery model: docs/archive/task-reports/runner-daemon-queue-recovery.md Run-record event profile: docs/reference/v2-run-record-event-profile.md

This document defines the local queue record schema and read-only projection contract needed before any queue file parser, queue writer, lease acquisition, foreground queue consumer, daemon worker, or queue execution exists. Queue / runtime records are [preview/bounded]: disabled by default; schema reserved. It is documentation-only. It does not implement queue readers, queue writers, leases, queue execution, daemon behavior, background workers, watchers, schedulers, auto-restart, live adapter execution, hosted or network APIs, credential handling, plugin runtime, marketplace behavior, mobile/LAN action controls, push controls, workflow or dependency changes, destructive operations, secrets, approval writers, or runtime expansion.

1. Goals And Non-Goals

The queue schema is an inert local metadata contract. It lets later tasks review and test how queued work would be represented without making the queue an authority to run anything.

Goals:

• define candidate local queue file locations before implementation;
• define queue entry fields, allowed states, and transition rules;
• define privacy, redaction, path-scope, sensitive-file, and safe-mode gates;
• define how future read-only dashboard, verify, and health projections must classify records;
• define test expectations for TASK-0054's later non-executing reader.

Non-goals:

• no queue parser, queue writer, queue repair, lease acquisition, cancellation command, daemon command, worker loop, scheduler, watcher, retry engine, foreground queue consumer, adapter executor, approval writer, or run-record writer is added by this contract;
• no hosted queue, remote queue, network call, credential flow, marketplace fetch, plugin runtime, mobile/LAN action, push, workflow edit, dependency install, destructive operation, or secret handling is permitted;
• no queue field grants authority. Queue records can describe only proposed or observed local state, and future execution still requires the permission model, matching preview and approval evidence, safe-mode gates, validation evidence, and a separately approved implementation task.

2. Queue File Location Candidates

Queue records are local, project-scoped metadata. Future implementations must prefer project-local relative paths and must treat unsafe configured paths as blocked metadata before reading them as authority or writing to them.

Reserved candidates:

Path	Role	Default behavior
.conductor/queue/entries.jsonl	Primary future append-only queue entry and transition log.	Missing means empty queue.
.conductor/queue/projection.json	Optional future derived read-only projection cache.	Missing means projection is recomputed or empty; it is never authoritative.
.conductor/queue/README.md	Optional human note for manual recovery.	Missing has no runtime effect.

Until a later implementation task explicitly adds queue config handling, these paths are candidates only. Existing Core commands must continue to work when the directory or files are absent.

Default behavior:

• queue behavior is disabled unless a future task adds explicit local config and that config is enabled;
• missing queue files mean empty queue state, not an error;
• disabled queue config makes any discovered queue records inert metadata;
• malformed, future-version, unsafe-path, symlink-escaping, hosted-dependent, credential-dependent, or unknown records are displayed as blocked metadata;
• read-only projections must not create the directory, create files, repair records, acquire leases, cancel entries, retry entries, or start workers.

Configured queue file paths in future tasks must be relative project-local file paths. Absolute paths, blank paths, paths that normalize outside the selected project, paths with a symlink component, paths that resolve to an existing directory, and paths under configured sensitive-file gates must block with queue_path_scope.

3. Record Envelope

The primary queue log is JSON Lines. Each line is one record envelope. Unknown fields must be preserved by future tooling when safe, but unknown fields never grant authority and may be summarized as blocked metadata.

Required envelope fields:

Field	Type	Requirement
schema_version	integer	Required. Starts at 1. Future versions block launchability until a migration task is accepted.
record_type	string enum	Required. queue_entry, queue_transition, queue_abandonment, or queue_recovery_note. Unknown values block projection for that line.
record_id	string	Required stable id for this log record.
queue_id	string	Required stable id for the queue entry.
created_at	string	Required UTC ISO-8601 timestamp.
updated_at	string or null	Required for the current record view; null is allowed for immutable creation records.
actor	mapping	Required local audit label. Must not contain private account ids, credentials, or raw transcripts.
state	string enum	Required queue state from Section 5.
privacy	mapping	Required redaction and forbidden-content flags from Section 8.
links	mapping	Optional links to BACKLOG, HANDOFF, DEVLOG, run records, approval ids, docs, or reviewed artifacts.

record_type: queue_entry creates or restates an entry. queue_transition records a state change. queue_abandonment records a deliberate terminal stop. queue_recovery_note records read-only recovery classification, such as a stale lease or malformed future-version record. None of these records executes anything by itself.

4. Queue Entry Schema

Each projected queue entry is derived from the latest safe local records for a queue_id. A future reader must fail closed when required fields are missing, malformed, contradictory, or privacy-unsafe.

Required fields for a projected entry:

Field	Type	Notes
queue_id	string	Stable id for the entry.
task_id	string	Selected BACKLOG task id. Missing blocks with missing_task_contract.
operation_id	string	Stable preview operation id.
operation_mode	string enum	preview, foreground-execute, or future background-execute. Unknown blocks.
preview_kind	string enum	Example: foreground-command, adapter-dry-run, or queue-metadata. Unknown blocks eligibility.
state	string enum	One of Section 5 states. Unknown blocks.
project	mapping	Project id/name when known, project_root, worktree, and branch.
path_scope	list of mappings	Repository-relative path scopes plus safety classification.
permissions_requested	list of strings	Least-privilege permission ids from the permission model. Unknown permissions block.
hard_stop_surfaces	list of strings	Hosted, credential, marketplace, mobile/LAN, push, workflow, dependency, destructive, or live-adapter surfaces discovered during preview. Non-empty blocks.
command_summary	string or null	Redacted human-readable command family/purpose only. No shell-ready text.
command_digest	string or null	Digest of reviewed command metadata when applicable.
environment_policy	mapping	Allowlist/no-secret summary; no environment values.
approval_id	string or null	Matching local approval when applicable. Null for non-approved states.
approval_state	string enum or null	missing, approved, expired, revoked, mismatched, or not_required_for_preview.
lease	mapping or null	Lease metadata from Section 7. Null unless a later task accepts lease records.
policy_generation	string or integer	Local policy/config generation used for this entry.
verification_plan	list of mappings	Required validation or review gates by name and expected result label.
rollback_plan	mapping	Disable, cancel, block, fail, abandon, or manual recovery expectations.
blocked_gates	list of strings	Empty only when every read-only projection gate is known and not blocked.
resume_next_step	string	Redacted next manual recovery step.

Optional fields may include adapter, plugin, run_id, priority_label, source, stale_reason, cancellation_reason, failure_kind, and review_gate_result. Optional fields are display metadata only and cannot widen permissions, paths, operation modes, or state transitions.

5. States And Transitions

Allowed queue states:

State	Meaning	Allowed next states
disabled	Queue behavior is unavailable by policy.	terminal
planned	A candidate entry exists but has not been previewed.	previewed, blocked, abandoned
previewed	Dry-run evidence exists; no work is approved.	awaiting_approval, blocked, abandoned
awaiting_approval	Operator or review approval is required.	approved, blocked, cancelled, abandoned
approved	Matching approval exists; no owner has a lease.	leased, cancelled, blocked, expired, abandoned
leased	A visible runner or future worker has a time-limited lease.	running, stale, cancelled, blocked
running	The approved operation is active.	cancelling, verifying, blocked, failed, stale
cancelling	Stop is requested and being handled.	cancelled, blocked, failed, stale
verifying	Required gates are being run or recorded.	completed, blocked, failed
completed	Operation and required verification passed.	terminal
cancelled	Operator or policy stopped the entry.	terminal
blocked	A gate, dependency, policy, malformed record, or stale lock prevents progress.	terminal until fresh preview/approval
failed	Execution or verification failed.	terminal until fresh preview/approval
stale	Lease or running state exceeded the recovery window.	blocked, abandoned
expired	Preview or approval expired before execution.	previewed, abandoned
abandoned	Operator or supervisor chose not to continue.	terminal

Transition rules:

• unknown states block projection with unknown_queue_state;
• transitions not listed above block with invalid_queue_transition;
• terminal states are never retried automatically;
• completed is valid only when explicit operation and validation evidence is present and no later invalidating cancellation, revocation, safe-mode, stale-lock, blocked, failed, or abandonment record exists;
• missing terminal evidence after leased, running, cancelling, or verifying is blocked or stale, never success;
• resuming any state that could mutate files, start a process, call a network, push, publish, handle credentials, change workflows, install dependencies, or destroy data requires a fresh preview and approval.

6. Operation, Permission, Adapter, And Plugin Gates

The permission model remains authoritative. Queue records only restate the operation metadata that future implementations must evaluate.

Projection must block when:

• operation_mode is missing, unknown, unsupported, or not allowed by the selected future task;
• permissions_requested contains an unknown permission id or a permission outside the selected task's scope;
• adapter or plugin metadata is unknown, disabled, incompatible, future-version, blocked, or missing required safety metadata;
• preview_kind, policy_generation, safety gates, verification plan, or rollback plan is missing or unknown;
• hosted, credential, marketplace, mobile/LAN, push, workflow, dependency, destructive, background, or live-adapter scope appears without a later accepted task that explicitly authorizes that exact surface.

Plugin manifests, adapter declarations, queue records, dashboard rows, run summaries, and local health rows are never authority. They cannot approve, execute, enqueue, lease, retry, cancel, push, fetch, install, or collect credentials.

7. Lease Metadata

Lease records remain blocked for implementation until a later task explicitly accepts them. This schema reserves the shape so read-only projection can fail closed when lease-like metadata appears.

Lease fields:

Field	Type	Notes
lease_id	string	Stable id for this ownership attempt.
queue_id	string	Must match the entry.
run_id	string	Related run-record id when known.
owner_kind	string enum	foreground_runner, daemon_worker, or manual_recovery. Unknown blocks.
owner_id	string	Redacted local process/session/worker label. No PID authority by itself.
acquired_at	string	UTC ISO-8601 timestamp.
expires_at	string	UTC ISO-8601 timestamp. Past, malformed, or future-skewed values block.
heartbeat_at	string or null	Latest heartbeat if a future daemon/worker exists.
policy_generation	string or integer	Policy/config generation at acquisition.
approval_id	string	Approval record associated with the lease.
safe_to_recover_after	string	Earliest timestamp when stale recovery classification may be shown.

Read-only projection may classify a lease as active-looking, stale, malformed, policy-mismatched, or incompatible. It must not acquire, renew, release, delete, reclaim, or repair a lease. A stale or malformed lease blocks execution and may be displayed as a recovery signal only.

8. Privacy, Redaction, And Forbidden Content

Queue records and projections are compact metadata. They must use default redaction and must prove forbidden content is absent.

Required privacy flags:

Field	Required value
redaction	default
contains_secrets	false
contains_credential_paths	false
contains_full_prompt	false
contains_raw_tool_output	false
contains_provider_payload	false
contains_executable_command	false
contains_unreviewed_external_body	false
promoted	false unless deliberately copied into a reviewed tracked artifact

Queue records must not store raw prompts, hidden prompts, private transcripts, full task launch text, raw stdout, raw stderr, raw tool output, full command logs, provider payloads, hosted payloads, marketplace reports, executable command arrays, shell-ready strings, raw adapter command templates, environment variable values, credentials, credential paths, token fragments, cookie names, browser profile paths, keychain paths, password-manager selectors, arbitrary file contents, diffs, dependency lock data, package hook bodies, workflow payloads, or unreviewed external document bodies.

If forbidden material is encountered, future tooling must record only a blocked category such as credential_scope_blocked, hosted_payload_blocked, raw_output_blocked, or executable_payload_blocked. It must not store masked fragments or reversible placeholders.

9. Path Scope And Sensitive Files

All queue paths and path-scope entries must be evaluated as local metadata and must fail closed before any future mutation, lease, or execution.

Path rules:

• queue record file paths must be relative project-local file paths;
• entry path_scope values should be repository-relative whenever possible;
• absolute paths are blocked unless a later task explicitly accepts a narrow local path scope, and even then they remain display metadata unless approved;
• .. traversal, paths resolving outside the selected project, symlink components, ambiguous aliases, missing project roots, existing directories used as file destinations, and blank paths block with queue_path_scope or path_scope;
• configured sensitive files from .conductor/config.yaml are hard stops unless the selected task explicitly approves handling and records a plan;
• no queue reader may normalize safety by creating, deleting, moving, resolving, or repairing paths.

Symlink behavior is deny-by-default. A path with any intermediate component inside the project that is a symlink to a directory outside the project is outside scope even if the textual path starts with .conductor/queue.

10. Malformed And Future Records

Malformed queue records are blocked metadata, not repair instructions.

Projection behavior:

Condition	Projection result
Missing queue file	Empty queue; severity info.
Queue disabled	Records are inert; severity info or blocked when unsafe.
Invalid JSON line	blocked record summary with malformed_queue_record.
Missing required field	blocked with the missing field's gate.
Future schema_version	blocked with future_queue_schema.
Unknown record_type	blocked with unknown_queue_record_type.
Unknown state	blocked with unknown_queue_state.
Unknown permission	blocked with unknown_permission.
Unknown operation mode	blocked with unknown_operation_mode.
Unknown adapter or plugin	blocked with unknown_adapter or unknown_plugin.
Unsafe path	blocked with queue_path_scope or path_scope.
Sensitive path	blocked with sensitive_path.
Privacy flag missing or forbidden content present	blocked with redaction_failed.

Unknown fields may be shown as unknown_metadata_present in a redacted summary. They cannot authorize launchability, widen scope, or be copied into approval, run, or execution records by a reader.

11. Read-Only Projection Contract

A future dashboard, verify command, health view, or local view may read queue metadata only as a projection. Projection is advisory and non-authoritative.

Allowed projection output:

• queue counts by state;
• per-entry queue_id, task_id, operation_id, state, severity, blocked gates, stale-lock classification, approval state, verification status label, and redacted next recovery step;
• links to reviewed local artifacts such as BACKLOG, HANDOFF, DEVLOG, run records, approval ids, docs, and commits already allowed by the selected task;
• health signals such as queue_disabled, queue_empty, queue_blocked, queue_malformed, queue_unknown_state, queue_unsafe_path, stale_lock, and recovery_required.

Forbidden projection behavior:

• no queue record creation, update, repair, truncation, compaction, deletion, migration, or promotion;
• no queue writer, lease acquisition, lease heartbeat, lease release, stale lock reclaim, cancellation mutation, retry, scheduling, daemon start, worker start, watcher start, auto-restart, subprocess launch, adapter execution, or approval creation;
• no network or hosted calls, credential prompts, marketplace fetches, plugin runtime, mobile/LAN action routes, push controls, workflow edits, dependency changes, destructive operations, or secret handling;
• no raw stdout/stderr, raw tool output, raw prompts, executable command arrays, provider payloads, credentials, credential paths, file contents, or diffs in projection output.

Read-only projections must remain usable when queue files are missing, disabled, malformed, future-version, or blocked. A projection failure must not break conductor verify; it should surface blocked metadata and leave manual recovery through HANDOFF, DEVLOG, BACKLOG, and reviewed artifacts.

12. No-Secret And No-Hosted Fallbacks

Missing credentials are normal. Queue records must represent credential need as disabled, unavailable, manual, or blocked metadata. They must not prompt for credentials, discover secret paths, read environment secrets, record credential selectors, or infer launchability from credential presence.

Missing hosted or marketplace access is normal. Queue records must represent hosted or marketplace need as disabled, unavailable, manual, or blocked metadata. They must not call hosted APIs, poll remote queues, fetch registries, upload records, sync hosted state, make online moderation decisions, or use remote availability to decide local launchability.

Manual import/export of redacted summaries and reviewed artifacts remains the fallback for external systems. Local records remain the source of truth.

13. TASK-0054 Reader Test Expectations

TASK-0054, if separately approved, must implement only a non-executing read-only queue reader/projection and verifier gate. Its tests should prove:

• missing .conductor/queue/entries.jsonl is an empty queue;
• disabled queue config makes entries inert metadata;
• invalid JSON, missing required fields, and future schema versions block;
• unknown states, invalid transitions, unknown permissions, unknown operation modes, unknown adapters, unknown plugins, and unknown policy fields block;
• configured queue file paths and entry path scopes block when blank, absolute, .. traversal, outside the project, symlink-escaping, existing directories, or sensitive-file scoped;
• privacy flags block when missing, false evidence is absent, or forbidden content categories are present;
• hosted, credential, marketplace, mobile/LAN, push, workflow, dependency, destructive, background, and live-adapter scopes block;
• read-only projection returns safe counts, blocked gates, severity, and recovery labels without writing queue, approval, run, or project files;
• no queue writer, lease mutation, subprocess launch, adapter execution, daemon/background behavior, network/hosted call, credential handling, marketplace behavior, mobile/LAN action, push, workflow/dependency change, destructive behavior, raw output storage, prompt storage, executable command storage, or secret handling occurs.

TASK-0054 must remain blocked until the supervisor explicitly authorizes that non-executing implementation slice. This schema does not unblock queue mutation, leases, queue execution, or daemon behavior.