core

Package: @adlc/core · Role: the shared library every gate imports.

What it is

@adlc/core is the foundation the whole toolkit stands on: every gate imports from it, and none keeps a private copy of what it exports. When a second tool needs a helper, the helper is promoted into core, with a test and no new runtime dependency, rather than copied; a defect in a core primitive is fixed in core so every caller gets the fix. That discipline is what keeps twenty-plus independently published tools behaving identically at their boundaries.

Downstream tools inherit five things from core: the exit-code convention, LLM provider selection, the append-only ledger, the ticket/rail/glob engine, and the mutation operators used by prosecution.

Exit-code convention

This is the contract. Every gate that builds on core reports its result the same way, so an orchestrator, hook, or CI job can branch on the exit code without parsing output. Core exposes it as three helpers: pass(), opError(), and gateFail().

The split between 1 and 2 matters: an operational error means the gate couldn't run, while a gate failure means it ran and found a problem. Collapsing them would let a broken environment read as a clean pass.

Provider selection

Tools that run an LLM pass do not embed provider logic. They call core's detectProvider / complete / fan helpers, which auto-detect a provider from the environment. Detection runs in a fixed priority order (cheapest and lowest latency first, per ADR-0007), matching the first provider whose key is present:

Force a specific provider with ADLC_PROVIDER (env) or a per-invocation --provider flag, which takes precedence over the env var. Model tiers (cheap / mid / frontier) resolve to provider-specific model ids and can be overridden with ADLC_MODEL_CHEAP, ADLC_MODEL_MID, and ADLC_MODEL_FRONTIER.

The keyless --prompt-only philosophy

No ADLC gate requires an API key to be useful. Every LLM-backed tool exposes --prompt-only, backed by core's promptOnly() helper: it prints the exact prompt the tool would send and exits 0. You can paste that prompt into any harness (a chat window, a different provider, an air-gapped review) and feed the answer back. Keys make the gate automatic; they are never a gate to entry.

Rail-engine primitives

The rest of core is the deterministic machinery the gates share:

• Ledger (.adlc/): appendEntry / readEntries back the append-only gate evidence, with sha256 / hashFiles for content hashing. Malformed lines are reported, never silently swallowed.
• Tickets & rails (.adlc/tickets.json): loadTickets, validateTicket, topoSort, and computeFloat (critical-path method) turn the ticket graph into an executable, dependency-ordered plan.
• Scope & glob: globMatch (*, **), inScope, and scopesOverlap are the conservative matchers rails-guard uses to decide whether an edit is inside a ticket's declared scope.
• Git: gitDiff, changedFiles, isDirty, plus coChange and churn for the logical-coupling signals hot-file and merge-forecast tools read.
• Mutation: mutate.OPERATORS (invert-comparison, bool-flip, null-return, off-by-one, logic-swap) and generateMutants / applyMutant power hollow-test, review-calibration, and gate-fuzzing.

test-kit (@adlc/core/test-kit)

Fixture helpers for node:test suites; typed by lib/test-kit.d.mts.

• tmp(t, prefix?) → a fresh realpath'd directory under os.tmpdir(), removed by a hook registered on t.after() (retrying transient ENOTEMPTY/EBUSY, FIXTURE_RM_OPTIONS). Fails closed: a t without a callable .after (none, null, a prefix string, an options object, or the context a describe-level before() receives) throws a TypeError and creates nothing.
• gitRepo(t, options?) → { dir, git, g }: a repo inside tmp(t) with a test identity, commit.gpgsign=false, gc.auto=0 and gc.autoDetach=false (no detached maintenance child writing into .git during removal). options is { prefix, branch, userEmail, userName } or a prefix string. Same context rule as tmp.
• createScope() → a context ({ after, dispose }) for fixtures that outlive one test callback: create in before(), await scope.dispose() in after(). Registering on a disposed scope throws.
• withScopedContext(fn) → runs fn(ctx) with a fresh scope and disposes it when fn settles; for code that calls test functions outside a node:test callback.
• runBin(binPath, args?, options?) → spawnSync of a Node script with DEFAULT_SCRUBBED_ENV (signing keys, bypass flags) removed unless allowEnv names them.

Go deeper

The full import surface: packages/core.