Independent implementation specification

This specification was derived by reading executable Python AST output with comments and standalone string expressions removed. The first pass covered the 39 Python files recorded in docs/review/core-catalog.json: package entrypoints, shared pipeline contracts/API/CLI, execution, missions and persistence. It did not consult the repository architecture, design, user guides or existing audit narrative. Executable string constants, SQL constraints and Pydantic field metadata were visible because they participate in program behavior. Mandatory repository/skill instructions and development-check instructions were read separately. Tests were consulted after the executable pass to validate identified defects.

This is a description of observed implementation and its contracts, not evidence that the product satisfies an external mathematical specification. Calls into projects, review, integrations, providers, dashboard, instructions, worker and search are described as boundaries; their internal correctness is outside this core pass and belongs to the separately recorded reviews. Browser behavior, actual provider/Forgejo/Zulip responses, deployed operator state, Lean theorem meaning, and adversarial load were not established by this pass.

Installation and durable data

The archon_horizon package exposes version 0.2.0; running the package invokes the pipeline CLI. Package initializers perform no eager service import. Packaged skill, descriptor and migration paths are rooted at the pipeline package through _resources.

The server requires an explicitly named PostgreSQL database and the psycopg driver. Connection setup fixes UTC, schema search path, statement and idle-transaction timeouts, a finite connection pool, connection validation and recycling. Migration is explicit and serialized by a schema-specific advisory transaction lock. Application startup checks the installed Alembic revision instead of migrating automatically. Transaction contexts roll back on failure and report long-held mutation locks. Domain mutation callers serialize allocation and ownership changes with the shared PostgreSQL advisory transaction lock; low-level numbering and record primitives require that caller discipline.

Schema records use UUID identities, creation timestamps and, for mutable records, positive monotonic revisions. Foreign keys restrict deletion. Enumerated lifecycle columns, partial unique indexes, JSON shape constraints and closure/evidence checks reject invalid storage states. Append-only artifacts, event observations, review evidence and record revisions are registered as immutable tables for migration enforcement. Parent-child mission, assignment, provider-thread and resource-claim relations preserve durable ownership independently of a provider process lifetime.

Blob content is addressed by SHA-256 and bounded before writing. A temporary file is written and fsynced in its destination directory, linked without replacing existing content, and followed by directory fsync. Existing content is read and verified. Reads verify expected size and digest; unavailable or corrupted durable content is an explicit error. Database blob rows may be deduplicated within a project and point to the shared content path.

Record helpers encode UUID/Decimal/datetime values, canonicalize JSON, resolve project ownership through stored parent relations, enforce cross-reference project consistency, increment revisions with optional compare-and-swap, create stable object references, snapshot business records with their relation IDs, and emit immutable changes. Blob writes occur outside PostgreSQL atomicity; failed database transactions may therefore leave unreferenced content for retention to reconcile.

Credentials and authority

Opaque credentials are generated randomly and stored as SHA-256 digests. Authentication rejects missing, oversized, revoked, expired or disabled-principal credentials. Human passwords use Argon2 verification, including a dummy verification for unknown usernames, and are rehashed when needed. Browser credentials have a configured expiry.

Installation administration is an explicit system grant for human/service principals. Project grants order viewer, worker and maintainer roles. An execution credential is authorized only while its agent execution is starting/running, its lease remains live, its assignment is running, and its run is active/paused/draining. Host credentials can operate only the enrolled host. Mission mutations by agents additionally remain in the assignment's delegated mission subtree. Objective maintainers and the objective planner receive the objective root as their permitted mission subtree. Assignment delegation remains in the same run and delegated tree; agents supply their own parent assignment and cannot enqueue unchanged work under another title.

HTTP reads authenticate before returning scoped data. Private conditional reads bind their ETag to the actor and representation and vary on cookies/authorization. Server configuration exposes only a redacted database URL. Browser writes enforce the configured origin, and cookie-authenticated writes require an origin. Request bodies are bounded even when the client streams without a Content-Length header. Credential-bearing reviewer responses use private no-store headers; the CLI writes reviewer tokens to a private file and reports its path.

Contracts, missions and ledgers

Pydantic contracts forbid extra fields and validate assignments. Text is strict, nonblank and NUL-free; slugs, counts, positive values, aware timestamps, normalized relative paths, absolute paths, Git ref names and selected object IDs have explicit constraints. Conditions are discriminated version-1 trees bounded to 128 nodes and depth 8. Model options inherit through omitted fields; explicitly supplied null options are rejected. Operation bodies, record creation and command arguments use named schemas and reject unsupported kinds/versions.

A project defaults to the graph workflow; legacy and milestone workflows remain selectable. Missions store an objective, acceptance criteria, an optional roadmap document, a child budget and explicit node/document/repository-path scope. An empty root scope is unrestricted. Child scope inherits when omitted and must be contained in the parent's scope; repository containment follows path segments. Delegation requires the current parent revision, an open parent, available child budget, acceptance criteria and a concrete handoff note. Linked graph records must remain in the explicit scope. Reparenting rejects cycles and authority-root escape. Narrowing scope must retain existing linked records and child scopes. Workers in objective runs may add acceptance criteria but need a maintainer decision to remove required outcomes.

Mission changes snapshot the contract, emit events and queue goal updates for active primary contexts. Pending older goal-update operations are superseded. Successful provider completion acknowledges the input's pinned mission/run/baseline revisions; reconciliation consumes goal updates already applied or cancels updates for terminal assignments. Completing a provider turn or assignment does not itself accept a general mission. Mission closure requires all descendants settled; cancellation also requires live assignments settled. Parent revisions change when child structure or closure changes.

Every assignment starts with a deliverable or bounded-decision obligation. Only the owning agent may mutate its live ledger; maintainers may account for settled owners. Obligation resolution records completed evidence, independent delegation, a pending scheduled owner, reconsideration, or replacement obligations. References stay within the project, unavailable owners are rejected, and delegation/supersession cycles are rejected. Recovery decisions require concrete evidence or replacement ownership. Completion refuses open obligations, unfinished provider requests, pending control notices, outstanding or failed external deliveries, unapplied goal updates and unsettled review generations. Handing the same mission unchanged to one unfinished owner does not satisfy completion.

Conditions evaluate to true, false or unknown. Boolean composition preserves unknown observations, aware deadlines schedule rechecks, and external-event evaluation excludes capacity/time/planning thresholds. Observers inspect lifecycle status, revisions, ledger handling, publication verification, discussion fingerprints, ready queue counts and current Forge observations. Stale or unavailable Forge cursors yield unknown. Assignment readiness also checks run state, expiry, explicit pause, automation ownership, run budgets, not-before/retry times and retained delivery waits. Recursive readiness is detected and observations are reused within one evaluation pass.

Objective runs and compatibility

An objective launch selects a versioned roadmap document, requires a maintainer, and rejects duplicate live owners and conflicting legacy ownership. It reuses a compatible root mission or creates one, chooses enabled hosts when none were supplied, establishes missing provider-account resource links, and installs missing advisory review policies for eligible repositories/phases. Explicit phase inputs and objective identity must agree. With no explicit phase sequence, it starts preprocessing, requests formalization, and adds postprocessing when a library repository exists.

Objective runs use category queue policies with fixed worker/maintainer permission roles, bounded pending queues, execution slots, optional session/token budgets, model defaults, retry settings and maintenance reservations. Work and maintenance are required categories. Objective planners own one active bounded pass and at most one scheduler-owned successor. Admission changes the successor recurrence identity to active and prepares the next bounded mission. Uncapped planners retain native delegation without reserving primary slots; an explicitly bounded planner is granted no native children. Completion closes an accounted planning mission when it has no open children, compares an executable frontier fingerprint, backs off unchanged passes, and pauses repeated idle planning. Changed objective/worker/Forge/host evidence may resume an idle planner; explicit operator pauses remain distinct.

Graph formalization may run without a milestone baseline. Compatibility workflows require their accepted baseline. An optional first baseline adopted by a graph run must match the run objective; later adoption keeps that objective. Postprocessing pins an existing verified source workspace/commit and a library target. New requests for the retired separate orchestrator profile are rejected; historical persisted legacy profiles still have compatibility lifecycle/recovery support.

Workers request a bounded maintainer decision by recording note and evidence against their own objective. Repeated identical maintenance requests reuse their durable owner. Phase acceptance is a maintainer decision with scoped evidence, rejects other unfinished sessions, retains the requested phase sequence, validates next-phase inputs and records phase history. The pending successor is cancelled. Automatic advancement waits for unfinished sessions, physical execution uncertainty and pending external deliveries. Human-approval mode pauses and prevents an agent from approving that boundary itself. Finishing all phases closes the root only when descendant missions are accounted for and drains the run; final completion separately checks unsettled work, publications, obligations, physical stops and deliveries.

Legacy runs retain recurring planning/maintenance and root-maintainer profiles. Their legacy automation specifications are separate from objective ownership, and objective code rejects generic competing automations. Legacy handoffs preserve unresolved findings in maintenance obligations rather than silently completing work. Recurring coordination watches fingerprint substantive publication, current-head review and worker-outcome evidence, bound repeated attempts, and require specific follow-up ownership. Idle capacity alone is not evidence of new work.

Admission, process ownership and recovery

The scheduler admits only healthy, recently heartbeating enabled host/harness pools whose shared limits and circuits permit work. Run and category budgets, unknown provider usage, workspace availability, retained host/harness affinity, unsettled provider requests and storage pressure can block admission. Native delegation is uncapped by default and consumes one primary slot. An explicit child cap reserves weight 1 + native_capacity in category slots, host slots and resource claims; diagnostics use the same weight. Uncapped observed children acquire individual shared-provider claims. Automatic account outage guards impose no normal concurrency quota; explicitly configured quotas still apply. The claim scan is bounded, rotates offsets, alternates supervision/category preference and orders runs by recent admission to limit starvation. Its cache is scoped to one claim/evaluation pass.

A retained primary provider context stays with its workspace, pinned harness configuration, skill bundle and applied model options. It cannot silently move to another host or be replaced after an uncertain failure. Fresh work prefers a free verified workspace; capable hosts may allocate an assignment-specific worktree with deterministic identity, fixed branch and pinned source commit. Workspace preparation is acknowledged only by its host, for that allocation, at exactly the expected commit and branch before provider submission.

Starting an execution snapshots assignment, mission and harness, pins bundles and sandbox data, reserves shared-resource units, marks the assignment running, creates or resumes a primary thread, issues a lease-scoped agent token, and returns the scoped launch grant. Large prompts are stored as assigned blob artifacts. Heartbeats extend the execution and execution-token expiry together, carry continuation/goal decisions, and enforce cancellation/expiry stop signals.

A lease expiry fences execution authority and makes active provider requests uncertain. Objective capacity remains busy until physical stop confirmation or reconciliation; logical terminal status alone does not establish that a process stopped. Host finish receipts validate the recorded execution epoch, settle requests, retain native identity, revoke credentials and release claims. A host may report preserved Git commits after fencing, but cannot start a provider request or acknowledge workspace preparation. Provider events must identify the execution's own thread/request, and changing native identity requires explicit context recovery.

Objective execution failure preserves the same pending session. Bounded transient recovery uses backoff, while unavailable native context, exhausted retries, persistent no-progress, budget limits and unresolved intents pause the session for a diagnosed recovery decision. Shared provider errors cool down capacity and can open a persistent circuit. Resetting the circuit requires an administrator note. Explicit context recovery requires physical stop confirmation in objective mode and records predecessor and recovery note. Legacy failure/retry semantics remain isolated compatibility paths.

The worker's local intent journal is represented by one stable blocker per assignment. Unresolved intents reopen that blocker; only a host observation confirming zero pending intents settles it. Repeated unchanged unresolved intents become a diagnosed execution failure. Preservation publications use dedicated Horizon recovery refs. Provider submission records exact input and revision pins before marking the request submitted; successful completion advances consumed revision acknowledgments. Unknown native observations are retained as durable events, and selected observations are projected to activity through subsystem boundaries.

HTTP and operator boundaries

The API provides explicit record creation, scoped bounded reads, lifecycle commands, mission/ledger changes, reviewer invocation endpoints, publication/Forge/Zulip intent endpoints, workspace/verification worker endpoints, schema discovery, conditional dashboard data, event invalidations, and packaged static assets. Domain and contract errors have structured responses; backend connection/pool errors are recoverable 503 responses. Login attempts are bounded per observed peer in process memory.

Most durable mutations require an Idempotency-Key and run in one locked PostgreSQL transaction with a stored request digest and receipt. Reusing a key with different content conflicts. Agent receipt lookup spans that assignment's execution principals so retained contexts can recover earlier intents. Responses over the inline threshold are persisted as project blobs. Host lease/health and verification-claim lifecycle endpoints have their own replay/epoch semantics. A lost response does not authorize issuing a replacement intent under a new key.

The event stream reauthenticates each batch, scopes visible project events, reports a gap when its cursor falls outside retention, bounds each batch, and sends resource invalidations rather than full records. Static assets resolve beneath the packaged asset root; dashboard routes return the built application and the site root redirects using only supported navigation query keys.

The CLI requires explicit configuration for installation operations. Initialization, setup recipes, objective/run launch and workspace verification offer concrete previews before apply. Migration, administrator creation, host-key issuance, storage backup/cleanup and watchdog operations are explicit commands. Agent commands require dispatched execution environment values; they never invent credentials. Request and upload files are bounded, writes are journaled by the client boundary, and raw reviewer credential printing is rejected. Workspace verification performs bounded read-only Git checks with hooks/fsmonitor/filters disabled and applies results only after eligibility and revision revalidation.

Review evidence and limits

The core catalog records every scoped file and qualified function, including nested functions, with source spans and SHA-256 identities. Entries record the reviewer-observed responsibility, contract/invariant and efficiency/documentation disposition; AST inventory metadata is supporting indexing evidence, not the basis for claiming a body review. The corresponding docs/review/core.md describes findings, fixes and executed checks. The complete repository audit is assembled from the other scoped catalogs; this core document makes no claim of complete review of code outside its listed scope.