📐peta-angel

The groupant beside tools/crab/src/angel.rs in the Mova repository: what the code computes, what it never does, how to go back from its outputs, its invariants, cost and checks.

Facts

Components

Obernants

The typed relations around the forward model: the behaviour complement (what the code never does), the reverse reconstruction (every input compatible with an output) and specialised views.

Model text

descriptant

Crab

Epoch2026-11-01: Crab is the persistent Rust deputy attached to fish annotation workers and the Eel GPU learner. Dolphin supplies independent Opus review through the existing terminal. The deputy uses a bounded local Unix protocol and durable request identities instead of conversational memory or hidden process restarts.

The key distinction is acknowledgment versus current state. Reusing an ID asks for its old receipt, even after another request changed the marker or a report appeared. Use a fresh ID for a fresh observation or deliberate new action. Reserved/uncertain work is inspected, never silently repeated. Opus acceptance, report presence and reviewed conclusions remain separate states.

A review found that raw16KiB excerpts were insufficient to bound escaped JSON. The response-size gate now runs before receipt persistence, with a NUL-report negative control. The client also rejects mismatched response IDs/schema. The attached-role configs and terminal session remain fixed. The explicit Whale launch extension uses trusted pinned server configuration, not arbitrary request-supplied shell or executable paths.

Optional Dolphin work now uses the same actor only after manual traffic has been quiet for60seconds. Admission remains separate from reservation and accepted terminal delivery; a failed dispatch never consumes a second automatic attempt. Review completion is stored separately from training. A second serialization control showed pretty-printed receipts could exceed the reader budget even when compact replies fit, so deputy artifacts use compact JSON.

Pinned exclusive Whale modes preserve separate marker authority. The ordinary lexical '..' alias counterexample is rejected by canonical root comparison; arbitrary filesystem isolation remains outside this model.

Current epoch: generic control and Dolphin are public. Roles are abstract; configured trusted terminal profiles replace model-specific identity restrictions. The original unprofiled session remains a compatibility branch. Provider/model labels are not actual-model attestation. Exact nonlegacy session/layout/owner observations and idle predicates are finite local evidence, not hostile-user authentication. Configured daemon execution remains independent of an active root chat.

Epoch 2026-11-02: generic read-only status attachments observe explicitly identified native workers without replacing older failed snapshots. The catalog is frozen in the loaded context; status presence adds no legacy marker authority. Bounded fixed projection keeps native source counters while excluding arbitrary prompt/receipt prose. Missing identity, future time and stale time remain distinct observations. The source implementation and local fixtures do not imply any live Crab cutover.

model

Crab local deputy

Forward and composition

A private Unix socket admits one newline-terminated JSON request per connection. The typed schema fixes schema=1, a bounded ASCII id and one admitted operation. Request fields cannot select arbitrary commands, paths or terminal sessions. Configurations are trusted operator-owned inputs: Crab pins the attached fish/eel config bytes, uses their known run roots and uses the explicitly configured consultant session and readiness/ownership profile; the unprofiled original session retains its legacy compatibility path. The tmux executable is configured, never supplied by a request.

Let k be a request ID and h the SHA256 of canonical JSON. A completed journal entry (k,h,response) returns the same response for another (k,h); a different hash conflicts. A reserved entry without a completed receipt returns uncertain and never dispatches again. Fresh work first syncs a reservation, performs its bounded operation, then syncs a completed receipt. This is an at-most-once dispatch policy under the cooperating single-server lease, not an exactly-once delivery or completion theorem. A crash can leave effects with only a reservation.

Status reads actual master/writer, up to eight annotation children (normally three) and the current eel trainer status. Timestamps/age are observations; no process health is inferred from a PID. read_reports projects known summary fields from trained metadata and its fixed 64-hex generation receipt, omitting large ID maps. Consultant reports are capped excerpts and remain unreviewed. Before journal persistence the response's serialized size is bounded; a violation yields a small stable response_limit receipt.

pause/stop only create owned common PAUSE/STOP markers; resume only clears the owned common PAUSE. Foreign markers, any STOP and the eel's trainer failure PAUSE block resume. These are asynchronous requests: active jobs may finish later. Fish and Eel remain attach-only and are not started, restarted or killed. The legacy start_whales operation reaches only an explicitly installed ExternalRoleHandler; the public default returns a missing-handler error. Request fields cannot install handlers or choose deployment paths. Concrete handler effects remain a separate implementation boundary. A paused process is not proved resumed by clearing a marker.

The compatibility operation consult_opus takes a separate lease, refuses earlier pending/uncertain reportless consults, and checks the configured terminal twice for the same recognized idle display. It writes one bounded read-only task file, loads an argv-addressed tmux buffer, rechecks idle, pastes literally and sends Enter. No interrupt key, provider API, account change or request-selected session is used. New session names need an explicit trusted terminal profile; the legacy session/profile remains compatible. Each delivery boundary is journaled before mutation. Accepted means dispatched, not finished; report presence is later evidence, not approval or linguistic correctness.

Invariant and cost

Private directory ownership/0700, socket0600, one listener lease, role-config pins, 16KiB request and 64KiB serialized response caps bound the transport. The client checks reply schema and request ID. Individual terminal commands time out after three seconds; socket I/O and client waiting are bounded. Heartbeats sync every ten seconds. A report excerpt is at most16KiB raw bytes, but JSON escaping can expand it; raw length alone is not a serialized bound.

Marker/status paths are fixed from pinned configurations. Journal/report names derive from an admitted ID hash. Work is O(known artifact bytes + journal scan) for observations, with a4096-entry scan bound and at most three report excerpts; generation metadata/receipts have2MiB read caps. The original receipt lookup and attached-role marker paths do not scan the corpus or touch model data. Delegated Whale operations retain the separate preparation, pin-verification and bounded receipt-observation costs. No latency or numerical-error approximation is claimed.

Limits

Filesystem updates are individually atomic/synced, not a distributed transaction with terminal delivery or worker loops. Direct terminal writers must cooperate with the Opus lease: checking UI and later pasting is not atomic against an unrelated human or process. Unknown/modals are refused conservatively. A report file may still be partial; report_present does not assert task completion. SHA256 binding assumes collision resistance; it is not an operator signature. Local private endpoint access and trusted configs are premises. Archive old observations deliberately before the journal-scan limit; there is no automatic retry or history deletion.

Optional idle Dolphin composition

With dolphin_auto=false (default), the actor does not reserve automatic reviews. When enabled, the server checks manual socket accepts first; only a WouldBlock boundary after at least60 seconds since the last manual reply admits a low-priority poll, at most every10 seconds. This prioritizes commands already queued at admission; it does not preempt a bounded automatic step already admitted. Busy/ambiguous terminal state or any reportless pending/uncertain consult prevents reservation. The actual Dolphin queue enforces its lifetime selected-ID quota; the adapter additionally checks review-only flags and a declared fraction at most10000ppm (1%) before terminal dispatch.

The actor first reads a completed pending report (bounded128000bytes), parses JSON or preserves plain critique, and calls Dolphin finish. These records remain in the separate review-only queue and cannot directly train or mutate the main annotation DB. Only then can next reserve one job; the same internal consult_opus request identity uses the existing terminal journal. A refused/uncertain reservation remains pending for inspection and is never automatically resubmitted. Manual consult tasks and automatic sentence reviews share one configured consultant actor. The exact report-file write is the sole tool exception for otherwise no-tools review tasks.

The consult task limit is12000bytes, compatible with Dolphin's limit; actual internal request serialization must still fit16KiB. Status exposes bounded Dolphin pending metadata and observes both the Eel actor status and legacy trainer status. Resume refuses internal Eel PAUSE/STOP as well as legacy trainer guards. JSON artifacts now use compact serialization; the completed-record encoding does not incur pretty-print expansion beyond the admitted reply plus fixed bounded receipt metadata.

External role hooks and observations

Legacy start_whales and whale_status accept no client role/task/path/limit arguments. Public control routes those hooks only to the explicitly installed handler; NoExternalRoles returns an error. An installed deployment may implement bounded cohort launches, but its binary/configuration/reservation semantics belong to its own source models. Earlier two-worker pool launch observations remain dated evidence in the private deployment model, not claims established by this public source. A start error is conservatively uncertain_external rather than proof that no external effect occurred.

attached_only=false reports configured capability, not proof of running workers. Marker/status observations and scientific validation remain distinct. Generic configured swarm-root pin/exclusivity/canonical alias checks remain public authority guards; they do not establish downstream handler correctness.

Continuous swarm authority

Optional swarm configuration is pinned independently of fish/Eel and is mutually exclusive with the Whale pool configuration (whale_config, or shark_config before the Whale rename). It routes only the admitted Whale start/status/marker operations to a configured manager. The created swarm directory is canonicalized and compared with existing role roots, closing ordinary '..' alias collisions. This establishes admitted canonical-path inequality, not arbitrary mount or subtree separation. Fish/Eel remain attached rather than relaunched. A status view of measured time or isolated research readiness does not establish a proved model, completed global review or production merge.

Public handler composition

Control/journal/report logic is public. Specialized status/start/marker calls cross ExternalRoleHandler and default to errors. Private Peta injects its implementation through serve_with_roles without a reverse dependency. Existing socket/wire identities remain compatible. Autonomous serving is an OS-process loop. Earlier integrated launch receipts do not establish a live cutover of this split.

Read-only attachment composition

Optional status_attachments is validated before endpoint setup and copied into the loaded context. Default empty preserves the previous response shape. At most eight explicit configured native status files are observed by the separately modeled status_observation module; requests cannot add paths or change the catalog. Catalog changes take effect only in a new context. Status role filtering does not turn attachments into controlled legacy roles: the separate control_scope states read_only_not_covered_by_role_controls. Legacy marker dispatch still uses only its previous role roots. The composed response retains its independent 64 KiB serialized budget; finite attached projections do not prove the aggregate fits.

The source-level error partition separates missing/malformed/oversized/identity failures from time freshness and from process/control/training authority. A current fresh artifact can coexist with a dead process. Native integration fixtures show unchanged default status, retained source counters, frozen catalog behavior, and a legacy Fish PAUSE that leaves the attached status bytes and parent marker untouched. This is finite source-grounded composition evidence, not a live deployment claim.

Worker supervision composition

Config gains optional workers and gpu_check, validated by the separately modeled workers module before any directory is created; a non-empty list adds the private run_root/workers directory. The context owns one supervisor behind a mutex. serve_full boots it only after taking the angel lease (adopt verified instances, start autostart workers), then calls one non-blocking tick per loop iteration before heartbeat and request handling. New journaled operations worker_status (optional worker), worker_start, worker_stop, worker_restart (required configured worker) take no role/task/target/limit/prompt fields; worker on any other operation is a protocol error. Results record intent and current state; completion is observed later. status adds a name-to-state map. The nested prompt callback (in_process) admits status, read_reports and the four worker operations, and still refuses pause/resume/stop markers, consult_opus and Whale operations. Legacy Fish/Eel role roots are untouched: worker control is a separate, configured process lifecycle, not marker control of attached roles. Negative control: admitting legacy markers on the prompt path turns the serve fixture red.

Dolphin pod (2026-11-04)

Dolphin pod. Consult targets are a list of named Dolphins (session, optional terminal profile, worker, pin); without the list one Dolphin consultant uses opus_session/consultant_terminal. consult_opus takes an optional dolphin name; journal records name their Dolphin and pending checks are per Dolphin. New operations consult_enqueue, consult_state, dolphin_list (also admitted in nested prompt calls; a direct consult_opus is not). consult_tick runs on idle serve-loop steps every 10 s: worker/GPU triggers, advice records for answered Crab-initiated entries, then at most one delivery per Dolphin when it has no pending consultation and its terminal is idle; a failed delivery is recorded, not retried. A refused ask may enqueue a bounded Crab consultation when consult_triggers.refusals is on. Terminal targets are =SESSION: (tmux 3.5 does not resolve =SESSION as a pane target; the live consult protocol failed with "can't find pane" before). check validates a configuration. Invariant added: no consultation result leads to any worker, marker or prompt operation.

default_fish_workers

Fish status observes workers worker status files, defaulting to crate::DEFAULT_FISH_WORKERS (2) and capped at 8 (2026-11-04; the default was 3).

Work flow, council and idle window (2026-11-04)

Forward additions: Config.flow and Config.council (council requires flow and 2..4 configured Dolphins); Context holds Flow, Council and Attention. supervision_tick(t) runs in the idle serve-loop step with the consult tick (every 10 s; flow evaluates every interval_seconds): flow events whose result is report, hold or an error become attention items; then the council ticks through CouncilPod. Operations flow_status (optional group, a configured kind) and attention, admitted in nested prompt calls; group belongs only to flow_status. ask_op records refused prompts (200-char excerpt, stage) for the council digest. flow_observe(config) answers the CLI flow-status without acting.

Terminal idleness: the idle marker may stand on any of the last idle_window non-empty lines (1..32, default 1), compared after stripping leading non-alphanumeric characters; busy/modal phrases are matched only in the bottom 12 non-empty lines. Invariant kept: a longer line ("DOLPHIN READY NOW") is not the marker; with window 1 a footer below the marker is not idle. Lock order: council -> flow -> workers.

Epoch 2026-11-04 (pool)

check lists each flow pool (members, jobs, lease_seconds).

Epoch 2026-11-04 (pool)

check lists each flow pool (members, jobs, lease_seconds).

Epoch 2026-11-04 (Whale rename)

The Whale operations are start_whales, whale_status and role whales; configuration keys whale_config, whale_swarm_config. legacy_request maps the names before the rename (start_sharks, shark_status, sharks) onto them right after parsing, so both reach the same validation, pins and journal; legacy_key reads whale_*, then shark_*. Evidence: whale_operations_require_server_configuration_and_no_request_arguments (a legacy shark_status gets the same refusal as whale_status) and the swarm tests, which configure the Crab with whale_swarm_config and with shark_swarm_config.

catalog

Typed obernants

behavior_complement

Domain: one leased server, private trusted artifact tree and normal returns. Observe role markers, terminal Enter delivery and role processes separately from journal writes. Unsupported operations/fields, invalid IDs, foreign markers and changed role pins cannot reach the modeled action; a known busy/modal/ambiguous terminal cannot reach paste/Enter after its failed check. The exclusion is source-derived and partial: rejection can still create a request receipt and read-only terminal observations. Counterexample to 'any error means nothing changed': a terminal failure after paste is explicitly uncertain. Native protocol/marker/busy and partial-delivery fixtures exercise these boundaries; no arbitrary crash proof is claimed.

reverse_reconstruction

Given (request ID, canonical-payload hash, completed receipt), compatible originating payloads lie in that hash fiber, under collision resistance. A cached acknowledgment cannot reconstruct current process state. A reserved receipt admits both no effect and an unrecorded effect; the inverse retains both rather than replaying. A report excerpt cannot reconstruct truncated text or the underlying code's correctness. Counterexample: pause, then resume with another ID, then reuse the first pause ID. The old acknowledgment returns while PAUSE stays absent. This is tested against actual marker operations.

duplicate_dispatch_exclusion

Type: partial_exclusion specialized to request identity. Fix a journal and one valid k. After reserving k, a second request with the same hash returns either cached completion or uncertain; another hash conflicts. Thus a second automatic action dispatch for k is excluded through this server path. This says nothing about a new ID or a writer bypassing the protocol. Counterexample to exactly-once completion: crash after terminal Enter but before final receipt. Oracles: reserved-consult and failed-enter fixtures observe zero replay; the socket fixture checks cached replies and conflicts. Status: partial source model plus finite native evidence.

serialized_budget_partition

Type: error_partition over response encoding. For JSON value v, let B(v)=len(serialize(v))+1 for newline framing. The response partition is B(v)<=65536 versus B(v)>65536; the latter maps to a bounded response_limit receipt before completed-journal persistence. Raw excerpt lengths do not determine this partition. Counterexample: three16KiB NUL reports occupy under64KiB raw but escape to about six times that size. The native control checks that the small error receipt remains readable and replayable and later status still works. No percentage bound is involved.

observed_terminal_admission

Type: partial_exclusion scoped to cooperative terminal access. Current admission requires the configured alive pane command, recognized exact idle footer, no known busy/modal cues and two equal captures before paste. New profiles also require the exact configured session name, one window/pane and matching @mova_crab_owner marker. The unprofiled original session retains the earlier claude/alive/footer compatibility path. The converse retains many terminal histories; no atomic idle interval or hostile-user authentication follows. Counterexample: a valid idle marker paired with foreign ownership is rejected before paste. Native local wrong-owner/different-provider/exact-target controls complement legacy busy/modal/delivery controls; no live UI certification is implied.

idle_review_admission

Type: partial_exclusion under a cooperative single actor and a fixed quiet interval. Let A denote opt-in, Q quiet_seconds>=60, M no queued manual request at accept, U recognized idle UI, and P no pending/uncertain reportless consult. Automatic reservation requires A and Q and M and U and P. Negating any condition excludes queue.next through this path. Counterexample to 'low priority can interrupt an active review': busy UI or pending work refuses admission before reservation. A manual request arriving after an admitted step can wait for that bounded step; no globally atomic priority or preemption theorem is claimed. Adapter fixtures cover auto-off, insufficient quiet, waiting manual command, busy UI, finish-before-next ordering, hard quota rejection and retained pending work with no resubmission. Actual lifetime quota integrity belongs to dolphin.rs and its SQLite tests.

trusted_pool_launch_exclusion

Type: conditional partial_exclusion on the compatibility start_whales path. Public control excludes client-selected worker paths/commands and implicit private handlers. NoExternalRoles rejects the hook. If an embedding installs a handler H, properties of H require its separate model and evidence; the public source cannot establish cohort size, child liveness or no hidden spawn by H. Earlier two-worker tamper/intent controls remain dated deployment evidence, not current public-hook proof. A hook error can follow an external effect, so uncertainty remains explicit.

whale_mode_authority_partition

Type: partial_exclusion. Domain: valid trusted Crab configuration and ordinary start/status/marker requests. Exactly one configured Whale mode selects a legacy cohort or the continuous manager; request fields cannot select executable/config paths. Swarm config bytes are separately pinned. An admitted swarm root must be canonically different from each existing Crab/fish/Eel root; this is not a disjoint-subtree, mount-alias or hostile-filesystem theorem. Counterexample motivating the check: lexical inequality alone admits an absolute '..' alias of the fish root, so Whales markers could affect fish. The canonical-path control rejects that ordinary alias. Capability, actor start, child progress, retained results and scientific validation remain different observations. Evidence: configuration mutation/exclusivity and alias negative controls; partial source-derived authority model, not generic remote execution.

external_handler_partition

Subject: specialized legacy role dispatch after ordinary protocol/configuration/journal gates. Domain: trusted local embedding and bounded admitted requests. Observation: hook reachability/result and durable request state. Assume intended embedding; downstream handler correctness is separate. Formula: C_None(x)=HandlerMissing for specialized hooks; C_H(x)=H(x) only after G(x). Unconfigured-role status still reports absence. Counterexample: configuration presence does not supply a handler; configured paths still fail with the public default. The explicit fake hook returns a bounded fixture without launching processes. This is an error partition/partial exclusion, not a full behavior complement or unique inverse. Evidence: external_operations_are_disabled_until_an_explicit_handler_is_installed, finite local Rust only; private runtime behavior remains outside this evidence.

configured_terminal_partition

Domain: an explicitly supplied nonlegacy consultant profile and trusted cooperative tmux metadata. Observe exact session/layout/alive command/owner plus two idle captures. Formula: Admit = ExactSession AND OneWindow AND OnePane AND ExpectedCommand AND Alive AND OwnerMatch AND StableIdle; model/provider identity does not appear in the role allowlist. Counterexample: identical READY text from foreign-owner is refused. Missing profile on a new session is rejected at configuration admission. Legacy config retains its explicitly weaker historical observation branch. Evidence: configured_model_agnostic_terminal_requires_exact_ownership_and_readiness checks alternate session/provider/model, default opus alias, foreign ownership, busy UI and exact argv targets with fake tmux; no real session/model call, authentication change or model attestation occurred. This is an observation/error partition, not a cryptographic identity proof or universal GUI verifier.

read_only_attachment_authority

Type: effect_boundary. Domain: a loaded valid context, legacy role requests and configured attachment paths. Observation: returned attachments and marker effects. Formula: status=legacy_status union Observe(A); Marker(role)=old_role_root(role) independent of A. An omitted A yields the prior response shape. Catalog A is frozen in the context; edits to an input value do not mutate that context. Counterexample: legacy Fish pause cannot be claimed to pause a distinct independently supervised worker merely because that worker appears in status_attachments. Evidence: native read_only_status_attachments_preserve_legacy_controls_and_loaded_catalog and invalid_attachment_catalog_fails_before_endpoint_creation. Assumptions: trusted local configuration and ordinary file semantics. This is a source-derived effect exclusion, not a proof of all downstream worker behavior or liveness.

ask_prompt_operation

op:"ask" (2026-11-03): arbitrary non-empty text with optional priority urgent|normal; no mode, role, task, target or limit. Frames up to 64 MiB for ask, 16 KiB for other operations. Journaled like every operation (same id → cached receipt, conflicting payload → id_conflict). Understanding is an installed PromptHandler (default: refused as not installed); its nested Crab calls run in-process and admit only status and read_reports. Waiting requests are answered urgent-first, then by arrival; a running request is never interrupted. Checked by the two ask tests; the priority test is red without the queue sort.

tests

Focused native evidence

Fourteen tests pass debug and release in the external harness with offline/locked resolution, at most two build jobs and serial test mode. They exercise Unix socket round trips,0600/0700 permissions, server lease/non-socket refusal, request deduplication and payload conflict, direct oversize frames/client size limits, wrong response schema/ID, owned/foreign marker rules, eel failure PAUSE and STOP refusal, stale cached pause acknowledgments, busy/modal/wrong-process Opus refusal, reserved and partially delivered consult no-replay, exactly-once mock terminal action sequence, report appearance and excerpt limits, and projection excluding a large trained-ID map.

The escaped-report negative control uses three16KiB NUL excerpts, verifies a small response_limit receipt before persistence, replays it and confirms later status remains readable. Fake tmux programs and fixture role directories are used; no real Opus task, live marker, teacher request, DB/model write or worker process is started by these tests. Observed finite controls are not actual power-loss or arbitrary UI-concurrency proof.

The follow-up harness stubs only the Dolphin API for standalone compilation; private trait fakes exercise automatic admission without touching a real review queue. Additional tests cover auto-off/quiet/manual/busy gates, report finish before one reservation, no repeated dispatch, an invalid >1% quota payload and retained reservation. A nested-array receipt control verifies pretty encoding would exceed128KiB while compact reply fits64KiB, then verifies the actual compact journal stays readable/replayable. Existing marker tests also observe the new Eel actor and refuse its internal failure markers. Integrated real-queue composition remains a root validation responsibility.

2026-11-02: the focused angel family passes 27 native tests, including six bounded status-observer controls and two attachment composition controls. Default-empty configuration preserves previous status shape; changed catalog input does not mutate an existing context; legacy Fish PAUSE leaves a separately attached status artifact unchanged. Invalid catalog validation precedes endpoint creation. An identity-gate removal mutation fails the exact native test with exit 101, and the original source is restored before the green rerun. No daemon restart or worker control is part of this evidence; direct read-only native observations are separate.

Worker operations (2026-11-03)

worker_operations_are_validated_journaled_and_limited_to_configured_names and serve_autostarts_and_prompts_admit_worker_control_but_not_consult_or_markers with fake shell workers. Red when the prompt path admits legacy markers; restored and green. 87 Crab library tests twice.

This page in Markdown → https://md.groupants.elamur.ai/free/en/mova/tools/crab/src/angel.rs.groupant/