Declare the work.Read what is ready.

A collaborative workspace

One real-time workspace request becomes an architecture, then API, data, and access constraints, then six streams. A later read-only guest requirement uses new task ids. ready lists dependency-ready work. invalidation lists the changed id and everything downstream. Neither call starts an agent or grants access.

The homepage construction is a visual analogy for software teams: shared contracts precede dependent work, a planned extension adds another crew, and only a non-bearing entrance changes during rework. It does not calculate building designs or certify structural safety. The moving model is driven by page position; reduced motion shows the complete result. Names under the model mark library behavior, host integration, or both. GraphIndex uses declared dependencies and an accepted set; readiness does not dispatch agents or reserve permission.

The homepage picture is an illustration. The lists on this page are GraphIndex results for that example, recorded in project-story.json. The fixture’s project is fictional. Its readiness and affected sets are computed. Library revision 2719ee143920d466a5e205af3904a528415b4d9d. Source module SHA-256 030002a26b63a082fe093764e1215ee46f4d77446044291e8b56999d288841ec. That revision id is not the package version in Availability.

Friendly names for the build streams: frontend_v1 / frontend_v2 Web, backend_v1 / backend_v2 API, data_layer Data, access_layer_v1 / access_layer_v2 Access, realtime Realtime, deploy Deploy. The contract tasks are shared constraints, not a seventh stream.

from optimal.graph import GraphIndex

tasks = [
    {"id": "brief", "depends_on": []},
    {"id": "architecture", "depends_on": ["brief"]},
    {"id": "api_contract", "depends_on": ["architecture"]},
    {"id": "data_contract", "depends_on": ["architecture"]},
    {"id": "access_contract_v1", "depends_on": ["architecture"]},
    {"id": "frontend_v1", "depends_on": ["api_contract", "access_contract_v1"], "writes": ["web/workspace"]},
    {"id": "backend_v1", "depends_on": ["api_contract", "data_contract", "access_contract_v1"], "writes": ["api/workspace"]},
    {"id": "data_layer", "depends_on": ["data_contract"], "writes": ["data/workspace"]},
    {"id": "access_layer_v1", "depends_on": ["access_contract_v1"], "writes": ["access/workspace"]},
    {"id": "realtime", "depends_on": ["api_contract", "data_contract"], "writes": ["sync/workspace"]},
    {"id": "deploy", "depends_on": ["architecture"], "writes": ["deploy/workspace"]},
    {"id": "integration_v1", "depends_on": ["frontend_v1", "backend_v1", "data_layer", "access_layer_v1", "realtime", "deploy"]},
    {"id": "verification_v1", "depends_on": ["integration_v1"]},
    {"id": "release_v1", "depends_on": ["verification_v1"]},
]
graph = GraphIndex(tasks)
accepted = {"brief", "architecture", "api_contract", "data_contract", "access_contract_v1"}
assert graph.ready(accepted) == [
    "access_layer_v1", "backend_v1", "data_layer", "deploy", "frontend_v1", "realtime",
]
change = graph.invalidation({"access_contract_v1"})
assert change["affected"] == [
    "access_contract_v1", "access_layer_v1", "backend_v1", "frontend_v1",
    "integration_v1", "release_v1", "verification_v1",
]

ready
access_layer_v1, backend_v1, data_layer, deploy, frontend_v1, realtime

affected
access_contract_v1, access_layer_v1, backend_v1, frontend_v1, integration_v1, release_v1, verification_v1

With the request, the architecture, and the three contracts accepted, six tasks are ready: Access, API, Data, Deploy, Web, and Realtime. Deploy depends only on architecture, so it is also ready earlier, beside the contracts, before those contracts are accepted. The six-stream result is the later observation, once the contracts are accepted and Deploy is still open.

Changing access_contract_v1 marks that contract, Access, API, Web, and the v1 integration, verification, and release tasks. It does not mark the request, the architecture, the API contract, the data contract, Data, Realtime, or Deploy. Data does not depend on the access contract. Realtime depends on the API and data contracts. Deploy depends on architecture.

The fixture keeps the old accepted v1 records as history and introduces v2 ids rather than relabeling the old ones. After read-only guest access, the retained accepted ids are api_contract, architecture, brief, data_contract, data_layer, deploy, and realtime. The new access contract is accepted on the v2 graph. Ready work is then only access_layer_v2, backend_v2, and frontend_v2: Access, API, and Web. Data, Realtime, and Deploy stay accepted.

The accepted set for each of those states is in the fixture. An accepted id has to be dependency-closed. If the API stream stops after Web and Access have been accepted, the same backend_v2 task is the one still ready. The other accepted work stays. Resumption is that task, not a new id and not a replay of Data, Realtime, or Deploy.

ready does not dispatch a worker, reserve web/workspace or the other write paths, or grant guest access. The host runs the agents, keeps the acceptance record, and qualifies whoever continues a task. Rebuild the index if the definitions change. The tech lead does not have to forward every step. Nothing here is a hosted fleet or an automatic search for an architecture.

A smaller export

Four tasks declare a CSV export. This is a low-level example of the same two calls. It is not the homepage story. Nothing here launches a worker.

from optimal.graph import GraphIndex

tasks = [
    {"id": "export_api", "depends_on": [], "writes": ["api/export.py"]},
    {"id": "download_ui", "depends_on": [], "writes": ["ui/export.tsx"]},
    {"id": "integration", "depends_on": ["export_api", "download_ui"]},
    {"id": "delivery", "depends_on": ["integration"]},
]
graph = GraphIndex(tasks)
accepted = set()
print("ready:", ", ".join(graph.ready(accepted)))
accepted.add("download_ui")
print("API interrupted; ready:", ", ".join(graph.ready(accepted)))
accepted.add("export_api")
print("after API passes:", ", ".join(graph.ready(accepted)))
accepted.add("integration")
print("after integration passes:", ", ".join(graph.ready(accepted)))
change = graph.invalidation({"export_api"})
print("API changed; revisit:", ", ".join(change["affected"]))

ready: download_ui, export_api
API interrupted; ready: export_api
after API passes: integration
after integration passes: delivery
API changed; revisit: delivery, export_api, integration

At the start, the API and the interface are both ready. After the interface is accepted, only the API is ready. Integration appears when both are accepted, and delivery appears after integration. Changing the API marks the API, integration, and delivery. The interface is not in that set.

An accepted id is your record of a result. This call does not check that the record is true. The host keeps the API patch, the failed check, and the interface result, and qualifies whoever continues the API task. Rebuild the index if the definitions change. ready does not reserve the declared write paths.

Task graph

The same index answers a smaller file-to-release plan. Edges run from a task to the tasks it waits on. An accepted set has to be closed: every prerequisite of an accepted task is accepted too.

from optimal.graph import GraphIndex

tasks = [
    {"id": "schema", "depends_on": [], "writes": ["app/schema.py"]},
    {"id": "api", "depends_on": ["schema"], "writes": ["app/api.py"]},
    {"id": "ui", "depends_on": ["schema"], "writes": ["web"]},
    {"id": "release", "depends_on": ["api", "ui"], "writes": ["dist"]},
]
index = GraphIndex(tasks)
assert index.ready({"schema"}) == ["api", "ui"]
assert index.invalidation({"api"})["affected"] == ["api", "release"]
assert index.descendants({"api"}) == {"release"}

ready({"schema"})
["api", "ui"]

invalidation({"api"})["affected"]
["api", "release"]

descendants({"api"})
{"release"}

With schema accepted, the API and the UI can proceed together. Changing the API marks the API and release. The UI is untouched. descendants leaves out the changed id. invalidation includes it, plus visit counts under operations. Neither call deletes an old result.

list_schedule plans a finite set of tasks onto identical workers. It orders ready work by the longest remaining path, then by task id, and it treats declared write paths as exclusive. Its returned optimality is not_claimed. Sibling paths such as src/a.py and src/b.py may overlap. A path and a prefix of that path may not. Absolute paths and parent traversal are refused.

Five independent jobs are the retained counterexample: the list schedule finishes at 7, and a bounded exact search can finish at 6. That search is optimal only inside its declared model, and only when the search says so.

Contracts

A blueprint pins requirements, checks, and task bindings by version. check_blueprint reads structure and source bytes. It runs no command. diff keeps the old declarations and names tasks affected by an explicit new version.

import json
from pathlib import Path
from optimal.blueprint import check_blueprint, diff

project = Path("examples/blueprint")
load = lambda name: json.loads((project / name).read_text())
v1, v2 = load("blueprint-v1.json"), load("blueprint-v2.json")
spec1, spec2 = load("tasks-v1.json"), load("tasks-v2.json")
assert check_blueprint(v1, spec1, project)["valid"]
assert diff(v1, v2, spec2, project)["affected_tasks"] == ["save.v2"]

check_blueprint(v1, spec1)["valid"]
True

diff(v1, v2, spec2)["affected_tasks"]
["save.v2"]

The v1 blueprint binds save and display. v2 supersedes save@1 with a new save version, adds the task save.v2, and leaves display in place. The diff result names save.v2. It does not execute checks, and it does not rewrite tasks that already passed. Old certificates stay about the versions they were issued for.

The checkout command for that example is:

optimal blueprint --project examples/blueprint --blueprint examples/blueprint/blueprint-v1.json --tasks examples/blueprint/tasks-v1.json

Run it from a checkout where this revision is installed. The command name in this revision is optimal.

Check station

Checked Git publication enters through optimal.station.serve. Importing the module starts no worker.

You pass a configuration, a Git repository, a checker, and an installer. Optional arguments are prepare_candidate, admit_publication, prepare_check, observe, wait_events, drive, and snapshot_end. drive defaults to true: serve builds the station and takes one step, then returns it. The call adds no worker, wake channel, or grant-order holder.

The station keeps durable source rows, slot order, check receipts, and publication that waited for those checks. You keep authorization, deployment, model sessions, and the decision that a result is accepted. optimal.integration replays Git history and older store shapes. It is not a second station, and this revision ships no example adapter that publishes by itself.

A foreground caller can submit its source before replay, then call step(blocking=True). Sandboxed candidate environments are a separate suite. They need macOS sandbox-exec, and graph planning does not need them.

Evidence

These figures are finite cases with their premises. They are operation counts or a published cost comparison. They are not a latency, a bill, or a proof that every future team is optimal.

Five jobs, two workers

Independent jobs a through e, durations 3, 3, 2, 2, 2, two identical workers, all available at time zero. Total work is 12, so the work bound is 6. list_schedule puts the longest remaining path first, then the task id, on the smallest free worker id. That policy is not claimed optimal.

Worker 0 runs a, then c, then e, and finishes at 7. Worker 1 runs b, then d, and finishes at 5. Makespan 7. One feasible partition puts the two jobs of length 3 on one worker and the three jobs of length 2 on the other, and finishes at 6.

from optimal.graph import exact_schedule

jobs = [{"id": key, "depends_on": []} for key in "abcde"]
durations = {"a": 3, "b": 3, "c": 2, "d": 2, "e": 2}
exact = exact_schedule(jobs, durations, workers=2, max_states=100_000)
assert exact["heuristic_makespan"] == 7
assert exact["makespan"] == 6
assert exact["optimal"] is True
assert exact["gap"] == 0

bounded = exact_schedule(jobs, durations, workers=2, max_states=1)
assert bounded["optimal"] is False
assert bounded["makespan"] == 7
assert bounded["lower_bound"] == 6
assert bounded["gap"] == 1

max_states 100000
makespan 6, optimal True, gap 0
heuristic_makespan 7

max_states 1
makespan 7, optimal False
lower_bound 6, gap 1

optimal is true only when the incumbent meets the lower bound or the finite event search finishes. A spent max_states budget keeps the best feasible witness, the lower bound, and the gap. The model is fixed durations, identical workers, no preemption, declared exclusive writes, and no release dates. The result holds for that model. Library version 0.6.0. The list-schedule counterexample lives in optimal.graph.exact_schedule and in the graph algorithms note in this source tree.

256 accepted tasks

A complete DAG of 256 tasks is already indexed, and every task is accepted. An older readiness scan walked the graph. The complete-acceptance path compares set size with the index and returns immediately.

The accepted set is duplicate-free, every id is already in the index, and the two sizes match. The indexed path returns an empty ready list after 256 membership hashes and no adjacency walk. The 33,152 visits in the difference are counted graph operations, not time, tokens, or money. Building the index is unchanged. Partial queries keep their previous cost, plus a cardinality comparison. The scoped Lean development is formal/optimality/CompleteSelection.lean. The optimality bundle correspondence says behavioral conformance, not a refinement of the Python process. Source note: docs/blueprint/complexity/complete-selection.md.

A native cost comparison

One published population, dated 2026-10-19, compared a whole-order native session (B0) with one session per node through the registered station (D). The quantity below is a geometric mean of paired simulated list-price cost, D divided by B0. It is not a latency and not a general saving. At the measured sizes, one session per node cost more.

The paired log cost-ratio slope against log2(nodes) was 0.644, with a seed-cluster bootstrap 95% interval from 0.609 to 0.675 (2,000 draws, seed 1596). Eligible completed orders passed in both arms. Success intervals were the full range from −1 to 1, so they do not show the arms are equivalent. One provider-capacity stop stayed unread. Original hardware was not recorded.

Publication record: source revision 34ed60b7e4ce6191c59f11ba32438e30f14a4b77, DevKit v0.5.0, station source c6b37aaa47deee1d7635a37d08549fcdbb103d90. Registration SHA-256 b37b508f205cdc9b285469a9eb98b643adcf820b02168b41e8077bba1b6ceb12. A fresh-clone replay on 2026-10-24, commit f9673f1df8fb0257bb5b5c57c2eb5b66c96d2cba, on an Apple M5 Max, repeated the analysis. That machine is the replay host, not the missing original hardware. The write-up in this tree is BENCHMARKS.md.

What a certificate can say

formal.certify compiles an optional Lean proof node and stores a certificate when the node asks for one. formal.certify_claim handles a closed claim of schema seaotter.dag-claim.v1. Families are structural.v1, needed_fact.v1, feasible.v1, and optimal.v1. Native v1 certifies the declared model. An optimal.v1 bound talks about feasible schedules in that model. It does not promote a team’s run into a global optimum, and a passing certificate does not make the rest of the Python library optimal. Requests for observed executions or for every possible execution stay unproved. Correspondence files in each proof bundle name the premises. Rows marked model-only make no current claim that the running Python matches the proof.

Availability

This page offers no public package install and no signup. Authorized collaborators install the private source. In this revision the distribution is optimal 0.6.0, the import is optimal, and the command is optimal. Python 3.11 or newer. The core library has no third-party runtime dependencies. Resources install under share/optimal. Version 0.6.0 removes the retired package and command aliases.

Graph calls need no Git, Lean, or model call. Native publication needs Git and the host ports above. An optional proof node needs the repo’s Lean toolchain. The full check-environment suite needs macOS sandbox-exec.

Optimal, formerly SeaOtter DevKit. This package adapts algorithms and operational lessons from SeaOtter, source revision 7952b4bf4e39697655f74dc21f120fb64263edb4. It includes no production account data, credentials, runtime databases, or customer evidence. Component-specific upstream license notices stay with the components.

The page uses self-hosted Manrope under the SIL Open Font License. The scene uses Three.js under its MIT license, with Motion for scroll progress. Copyright (c) 2024 Motion B.V. MIT License. Motion license.

MIT License

Copyright (c) 2026 SeaOtter

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.