@tiphys/kernel 0.0.0 → 0.2.0

package/dist/src/exclusion.d.ts

@@ -0,0 +1,389 @@
+/**
+ * THE SHARED EXCLUSION REGISTER (kernel plan M4, M4-P21).
+ *
+ * `src/lock.ts` states its own exclusion domain honestly at src/lock.ts:63:
+ * the lease excludes within ONE filesystem and ONE clock. Two environments
+ * that clone one fleet remote each get their own `state/orchestrator.lock`
+ * and BOTH acquire it, because `state/` is gitignored (src/fleet.ts:28) so
+ * the lease artifact never travels. M4-P20 measured that dangerous state and
+ * committed the captures; this module is the second exclusion layer that
+ * closes it.
+ *
+ * WHAT THE REGISTER IS. A compare-and-swap register on a dedicated git ref
+ * of the fleet's shared remote. The ref's value is a commit whose only file
+ * is `lease.json`; a write is `git push --force-with-lease=<ref>:<exact sha>`
+ * and the remote decides the race. M4-D-11 was PROTOTYPE-BLOCKED and M4-P20's
+ * probe closed it (delivery/verification/cross-environment-exclusion-probe.md:1).
+ * Three of that probe's findings are load-bearing here and are implemented
+ * rather than remembered:
+ *
+ *   1. ONLY `refs/heads/*` IS PUSHABLE. Tags, notes and custom namespaces are
+ *      refused with HTTP 403 (CLAUDE.md standing warning 14, re-measured for
+ *      this phase). So the "dedicated ref" is a dedicated BRANCH and the
+ *      default is `refs/heads/tiphys/lease`, which is visible in branch
+ *      listings and subject to any `refs/heads/**` ruleset.
+ *   2. THE EXPECTATION MUST BE AN EXPLICIT SHA. The bare `--force-with-lease`
+ *      form takes its expectation from the remote-tracking ref, so a routine
+ *      fetch re-arms it; the probe measured it CLOBBERING a live holder with
+ *      exit 0. `casWrite` below never emits the bare form.
+ *   3. NONZERO DOES NOT MEAN "I LOST". A transport failure exits 1 too, so
+ *      the result has THREE states and the indeterminate one is resolved by
+ *      re-reading the register rather than assumed either way.
+ *
+ * WHY THE STALENESS SIGNAL IS A COUNTER AND NOT A CLOCK (M4-P21 criterion 6).
+ * Two environments bring two clocks and `isExpired` compares a lease
+ * timestamp against the local one (src/lock.ts:171). Comparing one
+ * environment's wall clock against another's is exactly the measurement this
+ * layer must not make. So the register carries a MONOTONIC FENCING COUNTER
+ * that every write increments, and a holder is judged stale only when that
+ * counter has not moved across a duration measured entirely on the OBSERVING
+ * environment's own clock (two readings of one clock, never one reading of
+ * two). Where the register is reachable the counter decides and the command
+ * says `signal=counter`. Where it is not reachable there is no counter to
+ * read, only the local clock, and a clock is not a cross-environment signal:
+ * the command says `signal=clock` and REFUSES rather than falling back to
+ * local-only exclusion, which is the vacuous green this layer exists to
+ * prevent (criterion 7).
+ *
+ * C-2 (binding): nothing here reads a run identifier of a running program,
+ * probes liveness, sends a signal, or reads the kernel's virtual filesystem.
+ * Environment identity is a random id written once to a TRACKED fleet file
+ * (criterion 3), so it survives a reclaim and travels with a clone of the
+ * fleet; exclusion is decided by the register's counter and by git's own
+ * compare-and-swap verdict, never by anything about a machine.
+ *
+ * DECLARATION, NOT INFERENCE (criterion 1). The layer is entered only when
+ * the fleet home's own `package.json` declares it. With the field absent
+ * every function here returns "absent" before any subprocess is spawned, so
+ * a fleet that cannot reach a remote is not forced to switch the layer off
+ * globally and today's behaviour is unchanged for everyone else.
+ */
+/** The dotted path of the opt-in field inside the fleet home's package.json. */
+export declare const SHARED_EXCLUSION_FIELD = "tiphys.sharedExclusion";
+/** The remote a declaration defaults to. */
+export declare const DEFAULT_SHARED_REMOTE = "origin";
+/**
+ * The register ref a declaration defaults to. A BRANCH, deliberately: see
+ * finding 1 in this file's header. The plan's prose names `refs/tiphys/lease`
+ * and that namespace is refused by the shared remote this kernel is built
+ * against, so the default is the pushable form and the ref stays
+ * configurable for a remote with different rules.
+ */
+export declare const DEFAULT_SHARED_REF = "refs/heads/tiphys/lease";
+/** The file inside the register commit that carries the lease document. */
+export declare const REGISTER_DOCUMENT_NAME = "lease.json";
+/**
+ * The TRACKED fleet file carrying this environment's identity (criterion 3).
+ * It sits at the fleet root, outside the gitignored set at src/fleet.ts:28,
+ * so an environment that commits it keeps its identity across a reclaim and
+ * a clone of that commit reads the same id.
+ */
+export declare const ENVIRONMENT_ID_FILE = "tiphys-environment.json";
+/**
+ * Where this environment records what it last saw in the register. It lives
+ * under the gitignored `state/` prefix ON PURPOSE: it is a measurement taken
+ * on THIS environment's clock and it must never travel, or the duration it
+ * carries would be compared against a clock that did not produce it.
+ */
+export declare const OBSERVATION_FILE: string;
+/** How long the counter must stand still before a holder is judged stale. */
+export declare const DEFAULT_STALE_WINDOW_SECONDS = 900;
+export interface SharedExclusionConfig {
+    remote: string;
+    ref: string;
+    staleWindowSeconds: number;
+}
+export type SharedExclusionDeclaration = {
+    kind: "absent";
+} | {
+    kind: "declared";
+    config: SharedExclusionConfig;
+} | {
+    kind: "invalid";
+    reason: string;
+};
+/** The register's value: one lease document per register commit. */
+export interface SharedLeaseDocument {
+    state: "held" | "free";
+    envId: string;
+    counter: number;
+    acquiredAt: string;
+    expiresAt: string;
+    durationSeconds: number;
+    ref: string;
+}
+export type RegisterRead = {
+    kind: "absent";
+} | {
+    kind: "present";
+    sha: string;
+    document: SharedLeaseDocument;
+} | {
+    kind: "corrupt";
+    sha: string;
+    reason: string;
+} | {
+    kind: "unreachable";
+    reason: string;
+};
+export type CasOutcome = {
+    kind: "won";
+    sha: string;
+} | {
+    kind: "lost";
+    reason: string;
+} | {
+    kind: "indeterminate";
+    reason: string;
+};
+/** What this environment last saw, timed on this environment's own clock. */
+export interface RegisterObservation {
+    sha: string;
+    counter: number;
+    firstSeenMs: number;
+}
+/** Which of the two signals decided a shared-exclusion verdict. */
+export type ExclusionSignal = "counter" | "clock";
+export type SharedPreflight = {
+    kind: "proceed";
+    signal: ExclusionSignal;
+    expectedSha: string;
+    nextCounter: number;
+    takingOver: boolean;
+    line: string;
+    /** The document the register currently holds, when it holds one. */
+    current?: SharedLeaseDocument;
+} | {
+    kind: "refused";
+    signal: ExclusionSignal;
+    line: string;
+};
+/**
+ * Read the fleet home's declaration. Absent means the layer is off and no
+ * subprocess is spawned anywhere below; `false` is the same answer written
+ * explicitly. A field that is present and unreadable is INVALID rather than
+ * absent, because silently treating a typo as "off" is the shape that makes
+ * a guard green everywhere and protective nowhere.
+ */
+export declare function readSharedExclusion(fleetRoot: string): SharedExclusionDeclaration;
+/** The fleet root a lock path belongs to: <root>/state/orchestrator.lock. */
+export declare function fleetRootForLockPath(lockPath: string): string;
+export interface EnvironmentIdentity {
+    envId: string;
+    /** True when this call generated the id rather than reading one. */
+    generated: boolean;
+    path: string;
+}
+/**
+ * Read the environment id, or generate one and write it. The id is random
+ * and is generated EXACTLY ONCE per fleet home: every later call reads the
+ * file. Nothing about the machine enters it.
+ */
+export declare function ensureEnvironmentId(fleetRoot: string): EnvironmentIdentity;
+/**
+ * THE COMMAND-SCOPED IDENTITY THE REGISTER COMMIT IS WRITTEN UNDER.
+ *
+ * `git commit-tree` REFUSES without an author, and CI runners carry no git
+ * identity (CLAUDE.md standing warning 5), so a register write that relied
+ * on ambient configuration would work on a developer's machine and fail on
+ * every runner. These are the same two strings `tiphys init` already uses
+ * for the fleet bootstrap commit (EXT-F-02 option B): set as command-scoped
+ * environment variables on the invocation only, never written to user or
+ * global git configuration. They are repeated here rather than imported
+ * because `src/commands/init.ts` imports THIS module for the opt-in field,
+ * and a test pins the two copies equal so a drift reddens instead of
+ * surfacing as a runner-only failure.
+ */
+export declare const REGISTER_IDENTITY_NAME = "Tiphys Fleet";
+export declare const REGISTER_IDENTITY_EMAIL = "fleet@tiphys.invalid";
+/**
+ * The line of a git stderr block carrying git's OWN rejection marker.
+ *
+ * NOT "the first line", and M4-P20 paid for the difference: with
+ * `push.negotiate` true, git 2.43.0 emits a negotiation warning as the first
+ * stderr line of EVERY file-transport push, accepted and refused alike, so a
+ * signature taken from the first line cannot tell accept from refuse. The
+ * marker below is git's own text, never this module's, so the refusal
+ * signature stays captured rather than hand-written (T-003).
+ */
+export declare function rejectionLine(stderr: string): string | undefined;
+export declare function renderRegisterDocument(document: SharedLeaseDocument): string;
+/**
+ * Read the register. `ls-remote` establishes the value the compare-and-swap
+ * will be armed against, then the object is fetched so the document can be
+ * read. A failure at either step is UNREACHABLE, never "absent": the two
+ * must not be conflated, because "absent" means "nobody holds the lease" and
+ * would license an acquire.
+ */
+export declare function readRegister(fleetRoot: string, config: SharedExclusionConfig): RegisterRead;
+/**
+ * One compare-and-swap write. `expectedSha` is the value the caller read;
+ * the empty string means "I expect the register to be absent". The EXACT-SHA
+ * form is the only form emitted (finding 2 in this file's header).
+ */
+export declare function casWrite(fleetRoot: string, config: SharedExclusionConfig, expectedSha: string, document: SharedLeaseDocument): CasOutcome;
+export declare function readObservation(fleetRoot: string): RegisterObservation | undefined;
+export declare function writeObservation(fleetRoot: string, observation: RegisterObservation): void;
+export interface CounterJudgement {
+    stale: boolean;
+    /** How long the counter has stood still, on THIS environment's clock. */
+    unchangedForMs: number;
+    observation: RegisterObservation;
+}
+/**
+ * Judge a holder by the FENCING COUNTER, using two readings of ONE clock.
+ *
+ * A holder is stale only when the register's sha and counter are the same
+ * ones this environment first saw at `firstSeenMs` and that much of ITS OWN
+ * time has passed. Any advance of the counter resets the measurement, which
+ * is what makes a renewing holder safe no matter how far its clock is from
+ * this one: the renewal is visible as an increment, and an increment is not
+ * a timestamp.
+ */
+export declare function judgeByCounter(previous: RegisterObservation | undefined, sha: string, counter: number, nowMs: number, staleWindowMs: number): CounterJudgement;
+export type SharedIntent = "acquire" | "renew" | "release";
+export interface SharedPreflightInput {
+    fleetRoot: string;
+    config: SharedExclusionConfig;
+    envId: string;
+    intent: SharedIntent;
+    takeover: boolean;
+    nowMs: number;
+}
+/**
+ * Decide whether the caller may proceed, WITHOUT touching anything. Every
+ * refusal here happens before the local lease file is created, which is what
+ * makes criterion 7's fail-closed assertion observable: an unreachable
+ * register leaves no local lock behind.
+ */
+export declare function preflightShared(input: SharedPreflightInput): SharedPreflight;
+/**
+ * The one line a register write that was NOT won reports. It lives here
+ * rather than at the call site in `src/lock.ts` because it names the
+ * staleness basis, and the C-2 structural inspection over that file
+ * (test/lock.test.ts:534) forbids that vocabulary there; keeping the
+ * sentence in one place also means a reader sees the same wording whichever
+ * mutation lost.
+ */
+export declare function casFailureLine(ref: string, outcome: CasOutcome): string;
+/** Build the document a won preflight should publish. */
+export declare function buildRegisterDocument(input: {
+    state: "held" | "free";
+    envId: string;
+    counter: number;
+    nowMs: number;
+    durationSeconds: number;
+    ref: string;
+    acquiredAt?: string;
+}): SharedLeaseDocument;
+/**
+ * THE FOUR STATUSES, AS A CLOSED SET (M4-P22 criterion 1).
+ *
+ * `doctor` prints exactly one of them and a test compares the printed
+ * leading token against this array, so a fifth status cannot be added by
+ * writing a new sentence somewhere: it has to be added here, where the
+ * comparison sees it.
+ *
+ * THE FOURTH IS NEVER PASS. That is the DR-0038 shape reused rather than
+ * reinvented: a check whose question could not be asked reports a third
+ * state instead of being forced into a binary, because an unreachable
+ * register reported as `free` would license exactly the second live
+ * orchestrator this layer exists to refuse
+ * (delivery/decisions/DR-0038-the-declared-single-family-review-exception.md:1).
+ */
+export declare const SHARED_LOCK_STATUS_TOKENS: readonly ["not-declared", "free", "held", "unreachable"];
+export type SharedLockStatusToken = (typeof SHARED_LOCK_STATUS_TOKENS)[number];
+export type SharedLockStatus = {
+    token: "not-declared";
+    text: string;
+} | {
+    token: "free";
+    text: string;
+} | {
+    token: "held";
+    envId: string;
+    expiresAt: string;
+    text: string;
+} | {
+    token: "unreachable";
+    reason: string;
+    text: string;
+};
+/**
+ * A PURE READ of this environment's identity: it never generates one.
+ *
+ * `ensureEnvironmentId` above writes a file when none is there, which is
+ * right for `lock acquire`, the command that legitimately enters the layer
+ * and is about to publish a register document. It is wrong for a GUARD: a
+ * refusal must create nothing, and `doctor` must diagnose a fleet without
+ * changing it. An absent identity file therefore reads as "this environment
+ * is not the one the register names", which is the fail-closed answer.
+ */
+export declare function readEnvironmentId(fleetRoot: string): string | undefined;
+/**
+ * The register's state as one of the four statuses, WITHOUT writing an
+ * observation and WITHOUT generating an identity.
+ *
+ * `preflightShared` is deliberately not used here even though it answers a
+ * similar question, because it WRITES `state/shared-lease.observed.json` as
+ * part of judging staleness. A diagnosis that moves the thing it diagnoses
+ * is not a diagnosis, and the staleness judgement is not wanted here anyway:
+ * see `guardSharedRegister` below for why a stale holder still refuses.
+ *
+ * It DOES fetch, because `readRegister` fetches: the register object has to
+ * be local before its document can be read. That touches `.git/FETCH_HEAD`
+ * in the fleet home and nothing else, and it is stated here rather than left
+ * for a reader to discover.
+ *
+ * TWO CONDITIONS COLLAPSE INTO `unreachable` AND BOTH ARE NAMED IN THE
+ * REASON. A declaration that is present and unusable, and a register whose
+ * document does not parse, are not `free` and cannot be rendered as
+ * `held <envId> until <t>` because neither yields an envId or an expiry. The
+ * criterion's set is closed at four, so they take the one status that means
+ * "this question could not be answered", and the reason says which of them
+ * it was.
+ */
+export declare function sharedLockStatus(fleetRoot: string): SharedLockStatus;
+/**
+ * What a task-mutating command is allowed to do, given the register.
+ *
+ * `off` is the fleet that never opted in, and it is returned before any
+ * subprocess is spawned, so nothing about today's behaviour changes for a
+ * fleet home with no declaration.
+ */
+export type SharedMutationVerdict = {
+    kind: "off";
+} | {
+    kind: "allowed";
+    status: SharedLockStatus;
+} | {
+    kind: "refused";
+    reason: string;
+};
+/**
+ * THE CROSS-ENVIRONMENT HALF OF THE HOLDERSHIP GUARD (M4-P22 criteria 2
+ * and 3).
+ *
+ * `checkHoldership` (src/task.ts:439) answers "does THIS process hold THIS
+ * filesystem's lease". That question is answered entirely inside one fleet
+ * home, and src/lock.ts:63 says so: the local lease excludes within one
+ * filesystem and one clock. So in the state this function exists for, the
+ * local lease held by THIS environment and the shared register naming
+ * ANOTHER one, the old guard is GREEN and the fleet has two orchestrators
+ * mutating one set of tasks. That is the dangerous state, and a test that
+ * holds neither lease is green without this function and proves nothing.
+ *
+ * WHY A STALE HOLDER STILL REFUSES. `judgeByCounter` exists so that a lease
+ * whose fencing counter has stood still can be taken over, and that takeover
+ * is a LEASE operation: `tiphys lock acquire --take-over` advances the
+ * counter under the taking-over environment's id, and only then does the
+ * register name this environment. Reading staleness here instead would give
+ * `spawn` and `teardown` their own opinion about who holds the fleet, which
+ * is a second verdict about one lease from a second place, and it would have
+ * to write the observation file to reach it. The refusal names the command
+ * that resolves it, so the remedy is reachable rather than merely correct.
+ *
+ * THE REASON IS ONE LINE, and the callers hand it straight to the same
+ * single-reason path every other refusal uses.
+ */
+export declare function guardSharedRegister(fleetRoot: string, command: string): SharedMutationVerdict;