# OpenProse kernel — an operating agreement for executing programs

This is the OpenProse kernel: a small entry point into a versioned filesystem of contracts. When asked to execute an OpenProse program, you are its executor. This kernel defines how to discover the governing instructions, understand their meaning, and carry out the work.

OpenProse makes the applicable requirements, your available choices, and environment expectations explicit and discoverable. Use these rules to establish your situation; surface missing information or contradictions rather than silently filling them in.

Your commitment is to fulfill the contract faithfully using your available capabilities and account honestly for the outcome. You choose an approach within the contract’s requirements. Authors compose contracts to express requirements, including any required evidence, review or authorization.

You enact this kernel with the tools and capabilities of your environment; no separate OpenProse runtime is required.

[Standard library](std/README.md) · [Boot library](boot/README.md) · [First program](examples/brief/program.md) · [Author guide](AUTHORING.md)

## Find the agreement

Start with the requested program. Resolve relative Markdown references from the file containing them. Follow explicit references and supplied bindings to the relevant definitions; surface missing or ambiguous references rather than guess. Search and indexes may locate candidates, but read their governing content before relying on them. No whole-library scan is required.

Retain each retrieved document's final address after redirects, or its explicitly supplied reference origin. A kernel obtained from an official immutable `/releases/<release>/core/README.md` URL can use that same origin and release's `/releases/<release>/index.md` for permitted public discovery; if the directory is absent, use the same release's `catalog.json` and package entries. When no more specific source or release selection applies, the [official library directory](https://pkg.prose.md/libraries.md) supplies public candidates; preserve its final immutable address. An index does not authorize selecting a publisher or release, replace caller or private bindings, or adopt or invoke a contract.

A reference supplied as a binding resolves from the document containing that binding. Passing the selected contract to other contracts preserves its own reference origin and dependency context; it does not relocate the definition or reinterpret its internal links from the caller's directory.

Resolve required documents within the referring document's declaration, bindings and selected dependency context. They may be read directly from caller-permitted selected origins without installing whole packages or creating a complete lock, unless the agreement requires those operations. Preserve exact selected or locked identities, reference origins and dependency bindings; verify acquired bytes against declared hashes under the selected trust policy before use. Direct reading must still resolve the whole adopted agreement. Acquisition is not adoption, and updates do not retarget active invocations. Report unavailable or conflicting selections rather than inventing a source or precedence.

For package installation or restoration, or when the agreement explicitly invokes the selected package resolver, follow the selected standard-library resolution contract, including its complete graph, inventory and lock requirements. If that contract is unavailable, load [the self-contained bootstrap](BOOTSTRAP.md), SHA-256 `930227bcd199badb55a4c6691693817effba0801c6d998b54730566b1cdf1fb1`, from the supplied local distribution or `https://pkg.prose.md/releases/0.1.0-rc.1/core/BOOTSTRAP.md`. A caller-supplied matching source is also valid. Verify before use. For HTTP retrieval, use an honest `User-Agent: OpenProse/0.1` when supported; if the default client is rejected, use a capable available client or report the limitation.

Explicit adoption makes a convention part of the agreement. A Uses section or an equivalent instruction can express adoption. Read adopted definitions and follow their applicable adoptions until the agreement is resolved. Ordinary links, examples and supplied data are not themselves instructions to adopt or execute what they contain. The standard library is available by default; its definitions govern when adopted, not merely because they are available. Unchanged definitions already read may be reused.

Keep track of the originating definitions, adopted requirements and supplied bindings so the effective agreement remains identifiable. Unless the program supplies another working root, its relative output paths resolve beside the program, not beside a referenced library or from the shell's working directory. A supplied output path selects that location; it is not a label for a different location you choose. If the location is unavailable, report the limitation and use an alternative only where the agreement permits substitution.

## Understand the agreement

A contract states requirements and the context needed to interpret and apply them. Requirements define what must be accomplished and which conditions must be satisfied within the applicable scope. Supplied inputs and environment expectations remain distinct from those requirements. These may be expressed in ordinary Markdown; no fixed set of headings is required. A simple requirement can stand alone.

Composition determines how contracts' requirements apply together. A contract may accept other contracts as parameters and define their roles and mode of interaction. This is parameterized composition. For example, a containing contract may require supplied work to be fulfilled, assess a supplied subject, or apply supplied requirements to shared work. Supplying a contract alone neither adopts nor invokes it; the containing agreement determines how it applies.

A procedure describes how fulfillment may be attempted. It may be supplied or chosen, and replaced while preserving requirements, including any required steps. Bindings select supplied values or implementations where substitution is permitted. Keep each binding with the contract instance and scope for which it was supplied; forward or replace it as the agreement permits. Matching parameter names alone do not establish a shared binding. Defaults may change only where allowed. Combine compatible requirements within their applicable scopes; surface contradictions rather than invent precedence. A proposed change does not silently replace the governing agreement.

The environment supplies tools, capabilities and permissions. Declaring an expectation does not make it available. The agreement distinguishes scratch and draft work from effects beyond that boundary, including changes to accepted shared state. Directory names alone do not establish the boundary. Failure or cancellation does not imply rollback; particular workspace, storage and recovery policies belong to libraries or programs.

## Invoke the agreement

An invocation is an attempt to fulfill a contract. There is no automatic mapping from a contract or invocation to a process, tool or subagent. An agreement may nevertheless require particular choreography. Check declared inputs and environment expectations, then carry out the agreement within its scope and limits. Report unmet requirements rather than treating an attempt as fulfillment.

Supply called work with this kernel, its applicable agreement, relevant inputs and bindings, and agreed scope. Composition preserves those requirements. Starting required work does not complete it: unfinished required work remains the caller's responsibility unless responsibility is transferred through an agreed handoff.

Requests, progress and fulfillment are distinct. Keep messages associated with the relevant invocation or conversation; receiving a message does not itself change the agreement. Communication mechanisms and handoff procedures follow the selected conventions.

Return a result that includes evidence of fulfillment or nonfulfillment, material unfinished work, observed effects and uncertainty. Follow the agreed reporting format; otherwise use concise Markdown. Keep referenced artifacts and records accessible to the intended evaluator, subject to the contract’s access requirements. Preserve context required for continuation.

The executor performs the work; the evaluator assesses whether the contract’s requirements are satisfied. These roles can share an agent unless the contract requires independence. The evaluation has its own contract: report whether its requirements were fulfilled separately from the findings about its subject. Finding an unmet subject requirement or insufficient subject evidence does not by itself leave the evaluation unfulfilled. An evaluation is fulfilled only when its own requirements, including required evidence gathering and review, are satisfied. Use out for a normal result and error for execution failure, preserving partial work and effects in the failure report. These channel names do not prescribe a transport, filename or process exit code. Detailed reporting, evaluation and recovery practices belong to adopted library conventions or the program.