Utilities#
Small helpers the connectors and the framework share.
Who an audit record names — one ladder, shared by every surface that records.
An audit record uses its identity twice: once as the actor field inside the
envelope, and once as the <identity> path component of the spool directory
var/spool/<identity> it is written into. If those two were resolved by
separate code they would drift by a rung the first time one of them grew a
fallback, and the record would start naming one actor while filing under
another. This module is the single resolution, so both uses read the same
answer by construction.
The ladder, most specific first:
OSPREY_TERMINAL_USER— the multi-user deployment’s per-container user name. When it is set, a real person is behind the container.OSPREY_AUDIT_IDENTITY— what a container that hosts no single user is named instead: a framework service’s key,sidecarfor auth. Rendered by the same derivation that names the audit mount path, so the writer’s path and the mounted path cannot diverge. Without this rung a shared or framework service container would file everything under the process account —ospreyorroot, which names nobody.The local account (
getpass.getuser()) — the single-user laptop case, where the process account is the person.UNKNOWN_IDENTITY— an honest floor. An unresolvable identity must never cost the record.
Never the hostname. It looks like an identity and is not one: a host-network container reports the shared host’s name, so every service on the box would collide into one file, and a bridge-network container reports a random container id, so the same service would scatter across a new file per restart.
``OSPREY_AUDIT_IDENTITY`` must never join a scrub list. An executor sandbox
and a notebook kernel are severed from most of the environment they inherit,
and they resolve their own record directory through this ladder — the audit
directory and the per-identity control-state directory both. Rung 2 is the only
rung that survives that severing inside a container: the OSPREY_TERMINAL_
prefix is scrubbed by design, and the process account there names osprey or
root. Drop this one variable from a child and the child writes its records
and reads its narrowing under a name no reader looks for, which is worse than
either failing or being scrubbed — it is silently answering about somebody
else.
Stdlib only, and a leaf of this package. It is read where osprey cannot be
imported at all — connector-host children, executor sandboxes, notebook kernels
— and it is imported from mcp_server, from the interface apps and from the
services, where an osprey import here would risk a cycle between those
packages. osprey_connectors.identity re-exports every name below, so the
historical import path costs no second implementation.
- osprey_connectors.identity.AUDIT_IDENTITY_ENV: str = 'OSPREY_AUDIT_IDENTITY'#
The identity of a container that hosts no single user — a framework service’s key, or
sidecarfor auth. Rendered into every containerized service’senvironment:by the same derivation that names its audit mount. Audit-critical in both directions: it is stripped from every MCP server spec’s declaredenv:, so that no spec can repoint another service’s records at itself, and never from a child’s inherited process environment, which is where a sandbox or a kernel reads it - see the never-scrub rule above.
- osprey_connectors.identity.IDENTITY_ENV_LADDER: tuple[str, ...] = ('OSPREY_TERMINAL_USER', 'OSPREY_AUDIT_IDENTITY')#
The environment rungs, in the order they are consulted. Exposed so a test or a drift check can assert the order rather than re-encode it.
- osprey_connectors.identity.TERMINAL_USER_ENV: str = 'OSPREY_TERMINAL_USER'#
The multi-user deployment’s per-container user name. Spelled locally rather than imported from
interfaces.common_middleware, which owns the same constant for URL-prefix purposes: importing it would cost this module its leaf property, and the name is a deployment contract that does not move.
- osprey_connectors.identity.UNKNOWN_IDENTITY: str = 'unknown'#
What a record names when no rung resolves. A slim image often has no
pwdentry for its uid, which is normal rather than exceptional, so this is a routine outcome and not an error path.
- osprey_connectors.identity.acting_identity()[source]#
Return the identity an audit record should carry, per the module ladder.
Reads the environment on every call rather than caching at import: the markers are set per process by compose and by the entrypoint, and a value frozen at import time would be whatever the first importer happened to see.
Takes no arguments on purpose. A caller-supplied override would be a second ladder — the exact drift this module exists to prevent — so every surface gets the same answer from the same source or none at all.
Never raises:
getpass.getuser()raisesKeyError(Python 3.12 and earlier) orOSError(3.13+) for a uid with no passwd entry, which is ordinary in a slim container, and any other failure is equally not worth an audit record. Every failure lands onUNKNOWN_IDENTITY.- Return type:
str
- osprey_connectors.identity.usable_identity(value)[source]#
Return value stripped, or
""if it cannot serve as an identity.A rung must produce a value that works for both uses or it has not produced an identity at all. Empty and whitespace-only values are the unset case spelled differently — a rendered-but-blank
environment:entry, an env var exported as"". Values carrying a path separator or naming a relative directory are rejected because the same string becomes a directory name undervar/spool/, where../elsewherewould file one service’s records into another’s mount.Rejection is deliberately narrow: it covers what breaks path semantics and nothing else. A stricter character allowlist would turn a legitimate account name into
UNKNOWN_IDENTITY, which loses more than it protects.- Return type:
str
Declarative relative timestamps, resolved against an anchor at load time.
Demo and seed data (simulation scenario bundles and their narratives, seed
files the generic ARIEL adapter reads) express timestamps relative to “now” —
{days_ago, time} — rather than as absolute dates. They resolve to concrete
datetimes at the moment data enters the system (osprey sim apply and the
deploy-time seed for scenario narratives; osprey ariel ingest/quickstart
for the generic adapter), so the data always lands at a
recent, deterministic wall-clock position without ever mutating the source file
at build time.
This is the single shared primitive, living in osprey_connectors so
neither the simulation engine nor the ARIEL ingestion layer depends on the
other.
- class osprey_connectors.relative_time.RelativeTimestamp(days_ago, time)[source]#
Bases:
objectA timestamp expressed relative to an apply-/ingest-time anchor.
days_agois a whole-day shift back from the anchor date;timepins the resolved time-of-day (tz-naive local), so hardcoded prose clock times in an entry body stay consistent with the resolved timestamp.- days_ago: int#
- time: time#
- __init__(days_ago, time)#
- osprey_connectors.relative_time.resolve_relative_timestamp(spec, now)[source]#
Resolve a relative timestamp against an anchor
now.Shifts
nowbackspec.days_agowhole calendar days and pins the resolved time-of-day tospec.time. The shift is computed on the date component, so it is DST-safe (it counts calendar days, not 24-hour spans) and the resolved wall-clock time is exactlyspec.timeregardless of any DST transition between the two dates. The result carriesnow’s tzinfo (naive in, naive out).- Parameters:
spec (RelativeTimestamp) – The relative timestamp (whole-day offset plus time-of-day).
now (datetime) – The anchor instant. For scenario bundles this is the shared apply-time T0 (so narrative and telemetry resolve against one clock); for generic ingestion it is the ingest-time “now”.
- Returns:
The resolved timestamp, with the same tzinfo as
now.- Return type:
datetime
Replace a file whole: the one way OSPREY rewrites a file in place.
Every writer that rewrites a file calls atomic_replace(), so a reader
sees the old file or the new one and never a mix, a crash never leaves half a
file, and the file’s mode never depends on the process umask.
It also states, once, the shape of a group-shared location: a place written
and read under several uids that reach one another through the setgid group
of its directory. Such a directory is SHARED_DIR_MODE, created through
ensure_shared_dir(); a file in it is SHARED_FILE_MODE, and a lock
in it SHARED_LOCK_MODE:
<location>/ 2770 setgid: every entry below takes its group
<identity>/ 2770 every level a writer creates, set exactly
record.json 0640 read by the group, written by its owner
record.json.lock 0660 taken by every writer in the group
This module uses the standard library only. The Claude Code hooks run under
the system python3 and import nothing from OSPREY, so they ship this file
beside them as .claude/hooks/osprey_safety_file.py, a byte-identical copy
that tests/hooks/test_osprey_safety_file.py holds equal to this one. A
change is made here and copied there. That hooks catalog row is also the copy
the build stages beside the control-identity script that containers run by
path, so the byte pin keeps that copy equal to this module too.
- osprey_connectors.safety_file.SHARED_DIR_MODE = 1528#
A directory of a group-shared location. Setgid, so every entry created in it takes its group whatever uid created it; group-write, so a writer under one uid can replace what another wrote; nothing for
other, which would let it list the names inside.
- osprey_connectors.safety_file.SHARED_FILE_MODE = 416#
written by its owner, read through the directory’s group by the uids that never coordinate with that owner.
- Type:
A file in a group-shared location
- osprey_connectors.safety_file.SHARED_LOCK_MODE = 432#
whichever writer creates it first sets its mode, and every writer in the group has to be able to open it.
- Type:
A lock file in a group-shared location
- osprey_connectors.safety_file.atomic_replace(path, data, *, mode, sync='required')[source]#
Replace the file at
pathwithdata, whole or not at all.datagoes into a temporary file in the same directory, created here under a hidden name nobody can predict (.<name>.<random>.tmp), so it is never an existing file or a link someone planted; it is givenmode(whatever the umask), synced, and renamed overpath, and the directory is synced after the rename. A reader sees the old file or the new one, never a mix. When anything fails, the temporary file is removed and the exception propagates.sync="required"raises when the disk refuses to flush the file;sync="best_effort"carries on without the flush and still replaces the file.Choose
sync="required"exactly when the caller surfaces the failure to someone who can retry (an operator, a CLI, a build); choosesync="best_effort"when the caller swallows the error, because then a file replaced without its flush is more durable than the old file kept.
Create directory and the levels above it at
SHARED_DIR_MODE.Every level this call creates — the levels above the leaf as much as the leaf — is set to exactly
SHARED_DIR_MODErather than merely widened:mkdirhonours the umask and drops the setgid bit, so a level left as it made it is 0755 (otherlists the names inside) or, under umask 077, 0700 (the group cannot reach the files inside at all). A level that already exists is not this writer’s: deployment provisioned it, or another uid made it, and it keeps the mode it has. The levels are made one at a time from the top, so a level another writer makes first, between the look and the make, is left to that writer while the levels this call does make still get their mode. A mode is never set through a symbolic link.modes="required"raises when a mode cannot be set;modes="best_effort"keeps the directory as made, for a writer whose record is worth more in a narrower directory than not written at all.- Raises:
OSError – A level could not be created, or (
modes="required") a level’s mode could not be set, a link included (errno.ELOOP).