A Deployment’s Machines#

Which machines a deployment built beside the facility, and which of them its archive serves.

The deployment’s own virtual accelerator, decided in one place.

A deployment that stands a virtual accelerator up writes services.virtual_accelerator.port into its rendered config.yml — the build’s service injector does it exactly when the simulator is deployed, and the reach contract projects the same key into every attached render whose va target resolves. That one key is the deployment saying it built a simulator, and two readers decide from it:

  • virtual_accelerator_port() — the deployment’s shape: did it build a simulator, and on which Channel Access port? This is what makes the deployment’s own archive store the simulator’s (osprey_connectors.archive_targets): the store is seeded with the simulator’s history and the recorder samples the simulator into it, so a deployment that builds one has a va archive whatever machine its sessions start on.

  • virtual_accelerator_active() — an endpoint, right now: is the endpoint a va session would dial really this deployment’s own simulator container? The recorder’s enablement gate asks this of the va target’s derived endpoint before it writes a sample, because an endpoint is a real machine until the config proves otherwise, and a real machine’s readings must never land in a synthesized past.

The second predicate is the simulator’s twin of osprey_connectors.standin.live_standin_active(), with the same three conjuncts and the same fail-closed answers: the deployment built a simulator, the endpoint is on its port, and the endpoint is loopback. A va block whose gateways were moved off this host — to a simulator another host runs, or to anything else — fails conjunct 3 and is treated as a real machine, which is the truth: nothing says that endpoint is the container this deployment seeded a past for.

The config is read as nested sections only, because that is how the rendered config.yml is read by everything that acts on it.

osprey_connectors.simulator.VIRTUAL_ACCELERATOR_PORT_KEY = 'services.virtual_accelerator.port'#

Where a rendered config.yml states the simulator’s Channel Access port, dotted as the build’s service injector writes it, the reach contract projects it, and the VA connector fills unset gateway ports from it.

osprey_connectors.simulator.has_simulator(config)[source]#

Whether the build has a simulator.

The port alone answers no for an in-process virtual accelerator; the connector type alone answers no for a facility baseline that keeps its simulator. The simulator view cannot decide, because every build writes it.

Parameters:

config (Mapping[str, object]) – The full config mapping, as loaded from config.yml. The build validator, which sees an overlay, passes the overlay with services.virtual_accelerator.port filled in from the profile.

Return type:

bool

osprey_connectors.simulator.virtual_accelerator_active(config, *, endpoint_host, endpoint_port)[source]#

Whether endpoint is this deployment’s own simulator rather than a real machine.

All three conjuncts described in the module docstring must hold. Anything less — no simulator built, a port that does not match, a host that is not loopback or cannot be read at all — answers False: the endpoint is a real machine until the config proves otherwise.

Parameters:
  • config (Mapping[str, object]) – The full config mapping, as loaded from config.yml.

  • endpoint_host (str) – The host a session on the va target would dial.

  • endpoint_port (int | None) – The port it would dial, or None when the deployment has not resolved one — in which case there is no endpoint to match and no simulator to claim.

Returns:

True only for an endpoint that is the deployment’s own simulator.

Return type:

bool

osprey_connectors.simulator.virtual_accelerator_port(config)[source]#

The Channel Access port the deployment’s simulator serves, if it built one.

Parameters:

config (Mapping[str, object]) – The full config mapping, as loaded from config.yml.

Returns:

The port, or None when the deployment stood no simulator up. None also covers a value that names no port — blank, a mapping, a bare true — because a key that cannot be dialled is not a deployment saying where its simulator is.

Return type:

int | None

The deployment’s stand-in, decided in one place.

virtual_accelerator.live_standin: <port> stands a second virtual accelerator up — its own physics state, its own deterministic readout perturbation — and wires it in as the deployment’s own standin control target, dialled through its own control_system.connector.live_standin block. It is not a relabelled live: live always means the facility’s authored epics block, and an operator who selects standin has already said which machine they mean. Nothing about the stand-in pretends to be a simulation — the gateways really do dial it, real_machine stays true, and every warning, approval prompt and write refusal an operator meets is the one hardware shows.

One predicate lives here. live_standin_active() asks about an endpoint, right now — is the stand-in container actually up where a standin session would dial? It may not be re-derived by a caller. A guard that re-implements what the reader resolves can disagree, and the disagreement is a bypass — the same reason osprey_connectors.types owns the target resolvers and osprey_connectors.honesty owns the archiver pairing.

Nothing here is about the archive. The stand-in has no store of its own: it rehearses the facility’s real machine and is shown that machine’s past, while the deployment’s own store is the virtual accelerator’s — see osprey_connectors.archive_targets, which decides whose history an archiver: block holds, and reads no stand-in key to do so.

live_standin_active — the standin target’s deployed-container gate#

Since the stand-in is its own target, nothing here has to rename anything: the target carries its own name, and an operator on standin is told standin. What still has to be established is that the endpoint that target resolves to really is this deployment’s stand-in container, and not some other listener that happens to sit on this host. That is the question this predicate answers, and its three conjuncts must all hold:

  1. The deployment built a stand-in. services.live_standin.port is set and names a port. The build writes that block only when a profile asked for a stand-in, so its presence is the deployment saying it stood a second virtual accelerator up.

  2. The selected endpoint is that port. The endpoint a session would actually dial equals it. A config whose gateways were later moved to the real machine’s port is dialling a real machine, whatever a leftover services: block still says — the verdict follows the endpoint, never the leftover.

  3. The selected endpoint is loopback. 127.0.0.1, ::1, or the literal localhost. A container on this host is reached over the loopback interface; anything routed off the host is a different machine.

Deliberately no deployed_services conjunct. Attached projects and tier renders carry services: {} except for the keys their reach contract projects, so a conjunct on the deployed-services list would resolve to “not the stand-in” on exactly the renders a multi-user deployment hands its operators — the target offered to a single-user session and withheld from the same machine seen through a tier render. The projected port is the whole evidence, and it is enough.

An SSH tunnel is the case this predicate must not claim. Forwarding a real gateway to localhost:5064 satisfies loopback and nothing else: either the deployment stood no stand-in up (no services.live_standin block at all), or it stood one up on another port. Conjunct 1 or 2 fails, the endpoint is treated as a real machine, and that is the truth — the operator is one hop from hardware.

An empty or unparseable host answers False for the reason every honesty predicate in this package fails closed: the expensive mistake is telling someone that the machine in front of them is only a stand-in when it is not.

The config is read as nested sections only, because that is how the rendered config.yml is read by everything that acts on it. A top-level services.live_standin.port: line in that file configures nothing, and reading one here would let an inert line vouch for a machine.

osprey_connectors.standin.LIVE_STANDIN_PORT_KEY = 'services.live_standin.port'#

Where a rendered config.yml states the stand-in’s Channel Access port, dotted as the build’s service injector projects it and as this module walks it. One key, because one key is the whole evidence that a stand-in exists.

osprey_connectors.standin.live_standin_active(config, *, endpoint_host, endpoint_port)[source]#

Whether endpoint is this deployment’s stand-in rather than a real machine.

The standin target’s deployed-container gate: all three conjuncts described in the module docstring must hold. Anything less — no stand-in built, a port that no longer matches, a host that is not loopback or cannot be read at all — answers False, which is the honest default: the endpoint is treated as a real machine until the config proves otherwise.

Parameters:
  • config (Mapping[str, object]) – The full config mapping, as loaded from config.yml.

  • endpoint_host (str) – The host a session on the standin target would dial.

  • endpoint_port (int | None) – The port it would dial, or None when the deployment has not resolved one — in which case there is no endpoint to match and no stand-in to claim.

Returns:

True only for an endpoint that is the deployment’s own stand-in.

Return type:

bool

osprey_connectors.standin.live_standin_port(config)[source]#

The Channel Access port the deployment’s stand-in serves, if it built one.

Parameters:

config (Mapping[str, object]) – The full config mapping, as loaded from config.yml — not the services: section, since the whole point of the dotted key is that one walk answers for every reader.

Returns:

The port, or None when the deployment named no stand-in. None also covers a value that names no port — blank, a mapping, a bare true — because a key that cannot be dialled is not a deployment saying where its stand-in is.

Return type:

int | None

Which control targets the deployment’s archive serves, decided in one place.

A deployment carries one archiver: block, and a session can be pointed at up to three machines — the facility’s own (live), the virtual accelerator (va) and the stand-in soft IOC (standin). The block holds the past of some of them and not others. archive_targets() says which, so that a reader offering history on a target can ask whether the store it would open is that target’s own, and answer “no archive” when it is not — never another machine’s past under the selected machine’s name.

Every archiver belongs to one of two classes, and the class decides:

  • mongodb_archiver is the deployment’s own store. On a deployment that built a virtual accelerator it serves va, whatever machine its sessions start on and whether or not a stand-in was built beside it; on one that built no simulator it serves nothing.

  • Every other archiver except the mock is the facility’s archive (the EPICS archiver appliance, MYA, DOOCS, or a type this table does not know) and serves live and standin when its block names an address, nothing when it does not.

  • The mock, or no block at all, serves nothing.

The facility’s archive belongs to the facility’s machine, and the stand-in rehearses that machine. It is not something a deployment stands up for its simulation; it holds the real machine’s past, and that past is the one a stand-in session is shown, because what the stand-in rehearses is the procedure against the real machine’s history. It needs an address to count: a block that cannot be dialled is not a deployment saying it has an archive. The address is read per type (_ADDRESS_SETTINGS): the appliance’s url; MYA and DOOCS find their server without a setting (the client library’s configured myquery_server, the facility’s name service), so their block always names one.

The mongodb store belongs to the virtual accelerator. The deployment seeds it with the simulator’s synthesized history and the recorder samples the simulator into it (osprey.services.archiver_recorder); the stand-in is never recorded there and its offsets are never seeded there. So the store is the va target’s exactly when the deployment built a simulator — read through osprey_connectors.simulator.virtual_accelerator_port(), the build’s own statement that it stood one up — and no other target’s ever. control_system.type is not consulted: it names the machine a session starts on, and a deployment baselined on its stand-in or on the facility’s machine still seeds and records the simulator it built.

Nothing is the honest answer for the mock, which synthesizes and has no past, and for a block the connector factory would refuse — both settings spellings at once, or a settings value that is not a mapping — which serves no archive, so it claims none.

Pure: the answer is a function of the mapping alone. No environment variable, no file and no control-context record is consulted, which is what lets a supervisor call it at every restart and get the deployment’s answer rather than the calling process’s.

osprey_connectors.archive_targets.APPLIANCE_TARGETS: frozenset[str] = frozenset({'live', 'standin'})#

the real machine and the stand-in that rehearses it.

Type:

The targets the facility’s archive serves

osprey_connectors.archive_targets.archive_targets(config)[source]#

The control targets whose history this deployment’s archiver block holds.

Parameters:

config (Mapping[str, object]) – The full config mapping, as loaded from config.yml — not the archiver: section, because the answer for the mongodb store turns on whether the deployment built a simulator, which the section alone does not carry.

Returns:

The targets per the module table — APPLIANCE_TARGETS, _STORE_TARGETS or _NO_TARGETS. A target absent from the set has no archive: a caller holding it has nothing to offer, never a default to fall back on.

Return type:

frozenset[str]

osprey_connectors.archive_targets.archive_withheld(config, target)[source]#

Whether a session on target must be told it has no archive.

The agent’s reader of the one archiver: block asks this before it opens the connector, and the answer is the table’s: an attributed block whose targets do not include target is another machine’s past, and is withheld. The mock is not withheld here; whether it is an honest pairing is the archiver pairing’s question, asked at build and at the target switch.

Parameters:
  • config (Mapping[str, object]) – The full config mapping, as loaded from config.yml.

  • target (str) – The control target the session is on.

Returns:

True when the block is not the mock and does not serve target.

Return type:

bool

The one connector pairing a deployment may not have: invented history.

A virtual accelerator served from its container serves channels that move for modelled reasons — a corrector is stepped, the orbit responds, and the numbers a tool reads back are answers to what the deployment actually did — and its recorder writes that history as it happens. The live stand-in makes the same kind of claim from a soft IOC the deployment runs for itself. Neither machine existed before this deployment stood it up: the simulator’s only past is the store its recorder keeps, and the stand-in’s is the facility’s archive it rehearses against — they are the INVENTED_HISTORY_TYPES, reached over a network, and every question below is asked of that whole set rather than of the virtual accelerator alone. The mock archiver answers a history query the other way round: it synthesizes a plausible-looking series at read time, for questions nobody recorded the answer to. Configured together they produce an agent whose past is fiction and whose present is not, with nothing connecting the two — so the fiction can never be caught by disagreeing with the machine it claims to describe.

Refused at every moment a deployment can acquire the pairing: osprey build writes the config, osprey up stands the services up, the MCP server reads whatever config.yml it is pointed at — including one hand-edited long after the build — and, at run time, a session asks to be pointed at the simulator. Each site raises in its own vocabulary and names its own fix. What they share, and what lives here, is the question they ask and the reason they ask it.

The question is asked twice, because the two kinds of config are read by different readers, and a guard must resolve a key exactly as the reader it guards resolves it — otherwise the divergence *is* the bypass.

  • A build profile’s config: block reaches the rendered project through the emitter, which honors the dotted spelling (archiver.type:, the canonical one) and a nested mapping — both land on the same rendered leaf. Both are therefore live, and pairing_in_profile() fails closed when they disagree: whichever one wins, the profile has stated the archive twice and is free to be wrong once.

  • A rendered config.yml is read by ConfigBuilder and by MCPServerConfig, and both walk nested sections only — a top-level archiver.type: line there sets nothing at all. So pairing_in_rendered_config() resolves nested-only. A flat line is not evidence of an archiver; it is an inert line, and one this module names in its message rather than silently reading as “unset”, because someone who typed it deserves to be told why it did nothing.

Both readers fall back to the mock archiver when archiver.type is absent or blank (see the factory’s … is not set; defaulting to … warnings), so unset counts as the mock archiver at every site. That is the fallback the rule is really about: the common way into the pairing is not naming the mock archiver, it is naming nothing.

The venue is part of the question. The simulator served from its container has a recorder that writes its real history, so a synthesized archive beside it is fiction. The simulator served in process has no recorder, so a synthesized archive is the only archive it can have, and the chip says “Simulator”: that pairing claims nothing it cannot back up and is not refused. invents_history() asks it through talks_to_network(), the same wire fact every other check reads, so the type and the serving leaf are judged together and never the type word alone. A control system that states no type is the simulator in process, so it invents nothing either.

The run-time question is the same question asked one step early. A session that asks to be pointed at the virtual accelerator, or at the stand-in, has not changed anything yet, so the config’s own control_system.type is not the type to judge — the pairing to refuse is the one the switch would create. pairing_for_target() judges that one, taking the prospective control system from resolve_target() while the archiver still comes from the config, because the switch changes the machine and leaves the archive exactly where it was. The target is resolved through that shared resolver and never here: a guard that translates va privately is guarding a deployment other than the one the switch will produce, which is the same divergence-is-the-bypass this module refuses on the config keys. A target is judged as the section it builds from — the deployment’s own, with its type replaced by the target’s — so on a deployment whose own type is a real machine, va is the served container and is judged served.

class osprey_connectors.honesty.ArchiverPairing(is_invented_history, archiver_phrase)[source]#

Bases: object

What a config says about its archive, judged the way its reader reads it.

is_invented_history: bool#

Whether this config gives a simulated machine an archiver that invents its past — the thing all three sites refuse.

archiver_phrase: str#

How to name the config’s archiver back to whoever wrote it, ready to drop into a message after “archiver.type is …”. Says unset when unset, and says so about an inert flat line rather than pretending the key was never written.

__init__(is_invented_history, archiver_phrase)#
osprey_connectors.honesty.VA_MOCK_ARCHIVER_WHY = 'a virtual accelerator and the live stand-in are machines this deployment stands up for itself, with no past anybody recorded, while the mock archiver synthesizes history at read time. Paired, the agent reports a past that never happened and nothing can catch it — the one failure a simulated facility exists to make visible rather than to have.'#

Why the pairing is refused, in one sentence pair every site shares so the explanation cannot drift between them. Each site supplies its own fix.

osprey_connectors.honesty.invents_history(control_system_section)[source]#

Whether the machine control_system_section selects has no recorded past.

A type in INVENTED_HISTORY_TYPES that is reached over a network: the simulator served from its container and the live stand-in. The simulator served in process dials nothing and has no recorder, so it is not one. A serving value no reader accepts is judged served, the refusing side; the build names that value on its own.

Return type:

bool

osprey_connectors.honesty.pairing_for_target(config, target)[source]#

Judge the pairing a session target would create in a rendered config.

The same nested-only reading of the same file as pairing_in_rendered_config(), asked one step early: the control system is not the one the config selects but the one target selects, because a session pointed at the virtual accelerator gets a virtual accelerator — and one pointed at standin gets the stand-in — whatever the deployment was built for. The archiver is still the config’s own, since pointing a session somewhere else does not move the archive — which is exactly how a deployment honest at build time acquires the pairing at run time.

The prospective type comes from resolve_target() and is never worked out here, so this predicate and the switch it guards cannot disagree about where a target lands.

Parameters:
  • config (object) – The raw config mapping, as loaded from config.yml.

  • target (str) – The control target being asked for, one of CONTROL_TARGETS.

Returns:

The verdict and the phrase naming the config’s archiver, ready for a refusal that quotes VA_MOCK_ARCHIVER_WHY.

Raises:

ValueError – Propagated from resolve_target() when target is unknown, or is live on a deployment with no derivable live control system. An underivable target has no pairing to judge, and answering “allowed” for one would report a session as honest that cannot be established at all; callers establish that a target exists before asking whether it may be used.

Return type:

ArchiverPairing

osprey_connectors.honesty.pairing_in_profile(config)[source]#

Judge a build profile’s config: block.

Both spellings are live here — the emitter honors the dotted key and a nested mapping alike — so both are read, and a disagreement between them fails closed. Refusing an ambiguous profile is the same stance va_archiver_errors already takes on a duplicated connection key: one fact with two homes is free to disagree, and the build should not be the thing that picks a winner.

Parameters:

config (object) – The profile’s resolved config: block.

Returns:

The verdict and the phrase naming its archiver.

Return type:

ArchiverPairing

osprey_connectors.honesty.pairing_in_rendered_config(config)[source]#

Judge a rendered config.yml — the deploy config and the MCP server’s.

Nested sections only, because that is all either reader honors: a top-level archiver.type: line in this file is read by nothing, so treating it as a statement about the archiver would excuse the very config it fails to configure.

Parameters:

config (object) – The raw config mapping, as loaded from config.yml.

Returns:

The verdict and the phrase naming its archiver — which calls out an inert flat line when one is what misled the writer.

Return type:

ArchiverPairing

osprey_connectors.honesty.target_section(control_system_section, connector_type)[source]#

The section a target builds from: the deployment’s own, with its type replaced.

Return type:

dict[str, object]