jpmschweitzerandClaude Opus 5
5d83e1d2eb
Streaming as a decorator, first half. Each invocation of reach gets an id and every event it emits is tagged with it, which is what will let a detached run's log be read back and what correlates the lines of a run that streamed for nine minutes. No command signature changed and no command imports core.jobs — that is the point, per the D-263 amendment: a command must not know jobs exist, because the alternative is call-site discipline wearing a different hat. A ContextVar rather than a module global. A global is correct only until something runs two invocations in one process — which a test harness or a future batch verb does immediately, and which would then interleave two jobs' events under one id with nothing reporting an error. The job context is the OUTERMOST wrapper, and it has to be. @logged emits from its finally and @handle_errors emits its verdict while unwinding, so a context established inside either would already be reset by the time the two most important events are written — leaving them the only untagged lines in the log, and they are precisely the ones a detached run gets read back for. Fixed in passing: the job id used local time while every event's ts is UTC, so an id read 155327 beside its own first log line reading 13:53:27. Two hours apart reads as a logging bug every time someone correlates them by eye. New conformance invariant — nothing outside core/ may import core.jobs. My first version of it inspected only the module path, so it missed `from tooling.core import jobs`, where the name is in the import LIST and which is the form anyone would actually write. It passed while checking nothing. Rewritten to catch all three reachable forms and then verified by committing a real violation, which it named by file and line. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
64 lines
2.6 KiB
Python
64 lines
2.6 KiB
Python
"""Job identity, carried ambiently so no command has to know it exists (D-263).
|
|
|
|
Every invocation of `reach` is a job. It gets an id, and every event emitted
|
|
during it is tagged with that id — which is what lets a detached run's log be
|
|
read back later, and what correlates the lines of a run that streamed for nine
|
|
minutes.
|
|
|
|
**Ambient on purpose.** The alternative is threading a job through every command
|
|
signature, or having each command open one and remember to close it. That is
|
|
call-site discipline wearing a different hat, and it fails the same way: the
|
|
fortieth command of a long porting session forgets, and its output silently
|
|
loses its correlation with nothing to indicate anything is missing. `@command`
|
|
sets this up; commands never touch it.
|
|
|
|
A `ContextVar` rather than a module global, because a global is only correct
|
|
until something runs two invocations in one process — which a test harness or a
|
|
future batch verb does immediately, and which would then interleave two jobs'
|
|
events under one id with no error anywhere.
|
|
|
|
**Foreground runs get an id but no file.** Only detached runs persist (T-1277).
|
|
Writing a log for all four gate invocations on every push would create retention
|
|
pressure for output nobody reads. The cost is that a foreground run killed by a
|
|
timeout loses its output — which is exactly the case that should have used
|
|
`--detach`, so the tradeoff points the right way.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import os
|
|
import time
|
|
from contextvars import ContextVar, Token
|
|
|
|
_current: ContextVar[str | None] = ContextVar("reach_job_id", default=None)
|
|
|
|
|
|
def new_id() -> str:
|
|
"""A sortable, readable job id: `20260831T134512-a3f2`.
|
|
|
|
Timestamp-first so `jobs list` sorts chronologically by name alone, and
|
|
short enough to type or paste without friction. The four random hex
|
|
characters break ties within the same second — two invocations from one
|
|
script would otherwise collide and write to the same log.
|
|
|
|
**UTC, matching the `ts` field on every event.** Local time here would put a
|
|
job id and its own log lines two hours apart, which reads as a bug in the
|
|
logging every time someone correlates them by eye.
|
|
"""
|
|
return f"{time.strftime('%Y%m%dT%H%M%S', time.gmtime())}-{os.urandom(2).hex()}"
|
|
|
|
|
|
def begin(job_id: str | None = None) -> Token[str | None]:
|
|
"""Start a job context. Returns the token needed to end it."""
|
|
return _current.set(job_id or new_id())
|
|
|
|
|
|
def end(token: Token[str | None]) -> None:
|
|
"""End a job context, restoring whatever was current before it."""
|
|
_current.reset(token)
|
|
|
|
|
|
def current() -> str | None:
|
|
"""The id of the invocation in progress, or None outside one."""
|
|
return _current.get()
|