@skanl/brambo-projection 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+export { runProjection, groupByKind, hasFileChangedSince, resolveProjectionMode } from './engine.ts';
+export type { NativeFileSnapshot, ProjectionMode, ProjectionRun, RunProjectionOptions, } from './engine.ts';
+export { WRITABLE_CONFIG_KEYS, configPathFor, setConfigValue, type ConfigWriteOptions, type ConfigWriteResult, type WritableConfigKey, } from './config-write.ts';
+export { runRemediation } from './remediate.ts';
+export type { AdoptRemediationOptions, DiscardRemediationOptions, LegacyBlockLocation, ReleaseRemediationOptions, RepairRemediationOptions, RunRemediationOptions, } from './remediate.ts';
+export { ProjectionLedger, hashOwnedBytes, hashOwnedText, resolveOwnedPath, sameOwnedPath } from './ledger.ts';
+export type { ProjectionLedgerOptions, ProjectionLedgerRead, ProjectionLedgerScope, ProjectionLedgerState, } from './ledger.ts';
+export { createProjectionTargetFromTraits, readNativeMcpEntries, scanLegacyBramboBlock } from './formats.ts';
+export type { FileFormat, LegacyBramboBlock, LegacyBramboScan, NativeEntryShape, NativeMcpRead, ProjectionTargetTraits, TraitTargetOptions, } from './formats.ts';
+export { createClaudeMcpTarget, CLAUDE_MCP_TARGET_ID, CLAUDE_MCP_TRAITS } from './targets/claude-mcp.ts';
+export type { ClaudeMcpTargetOptions } from './targets/claude-mcp.ts';
+export { createCodexConfigTarget, CODEX_CONFIG_TARGET_ID, CODEX_CONFIG_TRAITS } from './targets/codex-config.ts';
+export type { CodexConfigTargetOptions } from './targets/codex-config.ts';
+export { createOpenCodeConfigTarget, OPENCODE_CONFIG_TARGET_ID, OPENCODE_CONFIG_TRAITS, } from './targets/opencode-config.ts';
+export type { OpenCodeConfigTargetOptions } from './targets/opencode-config.ts';
+export { CLAUDE_SKILLS_TARGET_ID, CLAUDE_SKILLS_TRAITS, CODEX_SKILLS_TARGET_ID, CODEX_SKILLS_TRAITS, OPENCODE_SKILLS_TARGET_ID, OPENCODE_SKILLS_TRAITS, SKILL_ENTRY_FILE, createClaudeSkillsTarget, createCodexSkillsTarget, createOpenCodeSkillsTarget, createSkillsTargetFromTraits, } from './targets/skills.ts';
+export type { SkillsTargetOptions, SkillsTargetTraits } from './targets/skills.ts';

package/dist/index.js

@@ -0,0 +1,15 @@
+export { runProjection, groupByKind, hasFileChangedSince, resolveProjectionMode } from './engine.js';
+// `atomicWriteText` is deliberately NOT here. A previous story un-exported it so
+// `@skanl/brambo-environment` could not reach it, and `packages/environment/test/guard.test.ts`
+// is the clause that notices if it comes back — the ledger is the sole authority
+// for what brambo writes into a vendor's file. Brambo's OWN configuration document
+// is a different thing and needs the same symlink-resolving write, so the WRITER
+// lives here, beside the primitive, and only the writer is published.
+export { WRITABLE_CONFIG_KEYS, configPathFor, setConfigValue, } from './config-write.js';
+export { runRemediation } from './remediate.js';
+export { ProjectionLedger, hashOwnedBytes, hashOwnedText, resolveOwnedPath, sameOwnedPath } from './ledger.js';
+export { createProjectionTargetFromTraits, readNativeMcpEntries, scanLegacyBramboBlock } from './formats.js';
+export { createClaudeMcpTarget, CLAUDE_MCP_TARGET_ID, CLAUDE_MCP_TRAITS } from './targets/claude-mcp.js';
+export { createCodexConfigTarget, CODEX_CONFIG_TARGET_ID, CODEX_CONFIG_TRAITS } from './targets/codex-config.js';
+export { createOpenCodeConfigTarget, OPENCODE_CONFIG_TARGET_ID, OPENCODE_CONFIG_TRAITS, } from './targets/opencode-config.js';
+export { CLAUDE_SKILLS_TARGET_ID, CLAUDE_SKILLS_TRAITS, CODEX_SKILLS_TARGET_ID, CODEX_SKILLS_TRAITS, OPENCODE_SKILLS_TARGET_ID, OPENCODE_SKILLS_TRAITS, SKILL_ENTRY_FILE, createClaudeSkillsTarget, createCodexSkillsTarget, createOpenCodeSkillsTarget, createSkillsTargetFromTraits, } from './targets/skills.js';

package/dist/ledger.d.ts

@@ -0,0 +1,193 @@
+import type { ProjectionLedgerRecord, ProjectionWarning } from '@skanl/brambo-contracts';
+import type { StaleLockBreak } from '@skanl/brambo-lock';
+/**
+ * Hash of the CANONICAL form of the text brambo placed at a native location.
+ *
+ * EOL is normalised because a file that git, an editor or a formatter rewrites
+ * from LF to CRLF has not been edited in any sense a vendor can observe — and
+ * `~/.claude.json` is rewritten by Claude Code itself. Treating that as an edit
+ * would make brambo disown every entry it has in the file. Format-specific
+ * canonicalisation (indentation, key order) happens in the strategies, which
+ * are the only code that knows what "the same entry" means per format.
+ */
+export declare function hashOwnedText(text: string): string;
+/**
+ * Hash of the exact BYTES brambo copied to a path.
+ *
+ * Deliberately not {@link hashOwnedText}: a materialised file is copied verbatim
+ * from a source brambo does not author, so "the same file" means the same bytes.
+ * Normalising EOL here would let brambo overwrite a file whose line endings a
+ * user deliberately changed, and — far worse, since this is the delete path —
+ * let it REMOVE one.
+ */
+export declare function hashOwnedBytes(bytes: Uint8Array): string;
+/**
+ * The EOL-normalised form of the same bytes, for the OVERWRITE comparison only.
+ *
+ * Never for a removal. A removal is decided byte for byte, because a false
+ * match there precedes `rm`; an overwrite decided byte for byte instead makes
+ * a skills root kept under `core.autocrlf` report every brambo file as edited
+ * forever, and the product has no adopt, force or reclaim path out of that.
+ */
+export declare function canonicalBytesHash(bytes: Uint8Array): string;
+/** Ownership keys must be one canonical spelling of a path, never two. */
+export declare function resolveOwnedPath(filePath: string): string;
+/** win32 paths differ in drive-letter and directory casing between processes. */
+export declare function sameOwnedPath(left: string, right: string): boolean;
+/**
+ * Whether `path` is strictly inside `root`. Both arguments must already be
+ * resolved — this predicate answers about paths, not about strings a caller
+ * hopes are paths.
+ *
+ * It lives beside {@link resolveOwnedPath} because it is the second half of the
+ * same rule: a path brambo acts on is CANONICALISED and then proven to be inside
+ * the location brambo owns. Every caller that skips either half has been a
+ * user-data defect — the removal path took raw ledger strings straight to `rm`,
+ * and a relative one resolved against the process working directory.
+ */
+export declare function isUnderRoot(path: string, root: string): boolean;
+/**
+ * The right to replace the WHOLE ownership document without merging.
+ *
+ * A module-scope symbol rather than a convention: the only way to hold it is to
+ * import it, so "one caller" stops being a claim a text scan makes and becomes
+ * something the runtime enforces. `test/guard.test.ts` pins who imports it.
+ */
+export declare const LEDGER_REPAIR_AUTHORITY: unique symbol;
+export type ProjectionLedgerState = 'absent' | 'readable' | 'unreadable';
+export interface ProjectionLedgerRead {
+    /** `unreadable` means the file exists but brambo must not write over it. */
+    readonly state: ProjectionLedgerState;
+    readonly records: readonly ProjectionLedgerRecord[];
+    /**
+     * Records `records` rejected, reduced to the smallest claim brambo can still
+     * ACT on. Empty unless the document holds damage, and read by `repair` alone:
+     * every other caller wants only what brambo can vouch for.
+     */
+    readonly salvaged: readonly ProjectionLedgerRecord[];
+    readonly warnings: readonly ProjectionWarning[];
+}
+/** Everything one target claims in one file — the unit a run replaces. */
+export interface ProjectionLedgerScope {
+    readonly targetId: string;
+    readonly filePath: string;
+}
+export interface ProjectionLedgerOptions {
+    /** Defaults to the OS home directory. */
+    readonly homeDir?: string;
+    /** Overrides the whole path; the default is `<home>/.brambo/projection-ledger.json`. */
+    readonly filePath?: string;
+    /** Bounded wait for the cross-process lock before a coded CONTENTION refusal. */
+    readonly lockTimeoutMs?: number;
+    /**
+     * Observes every stale/corrupt-lock break performed on the way to a write.
+     *
+     * A break is brambo deciding that a lock left behind by a dead process no
+     * longer protects anything. That decision is REPORTED rather than silent,
+     * because it is the one moment where the outer boundary steps aside.
+     */
+    readonly onStaleLockBreak?: (broken: StaleLockBreak) => void;
+}
+/**
+ * The hash brambo writes for a claim it can still ADDRESS but can no longer
+ * VOUCH for.
+ *
+ * Deliberately not hex. A real `contentHash` is `sha256` output, so this can
+ * never compare equal to one by accident — the never-matching property is
+ * structural rather than improbable. `isLedgerRecord` asks only for a non-empty
+ * string, and nothing anywhere validates the shape, so this survives a round
+ * trip and reads as `edited` forever: brambo knows which bytes the claim covers
+ * and admits it does not know what it wrote there.
+ */
+export declare const UNVOUCHED_CONTENT_HASH = "unreadable-after-repair";
+/**
+ * The exact bytes of the ledger document for a record set.
+ *
+ * Exported so a remediation can PREDICT the document it is about to write and
+ * report the byte delta before writing it, using the same serialisation the
+ * write itself performs. A second spelling here would let a preview report a
+ * size the act does not produce.
+ */
+export declare function serialiseLedgerDocument(records: readonly ProjectionLedgerRecord[]): string;
+export declare class ProjectionLedger {
+    #private;
+    readonly filePath: string;
+    constructor(options?: ProjectionLedgerOptions);
+    /** Never throws: the three states are what callers must distinguish. */
+    read(): Promise<ProjectionLedgerRead>;
+    /**
+     * Replaces the records this caller TOOK A POSITION ON inside one scope,
+     * keeping every other claim — including claims inside the same scope that
+     * landed after the caller's snapshot was taken.
+     *
+     * `examined` is the third parameter and it is required, because omission used
+     * to mean deletion and nobody could see it. The caller passes the entry ids it
+     * read out of its own ledger snapshot for this scope; `update` adds the ids it
+     * is being handed now. An id in neither set belongs to a writer this caller
+     * never saw, and survives untouched.
+     *
+     * WITHOUT IT, A CONCURRENT RUN ERASES CLAIMS IT DELIBERATELY LEFT ALONE.
+     * Measured on the binary: ten rounds of two concurrent `brambo init` over one
+     * home lost 20 of 40 claims, 20 of 20 processes exited 0, and no stderr line
+     * named foreign, skip, collision or ledger; the one-process control lost 0 of
+     * 40. A wider run lost 72 of 144 and left 16 vendor entries owned by nobody,
+     * after which `brambo doctor` exited 0 reporting `"drift": []` and a later
+     * `remove` + `init` could no longer take those entries back out — brambo had
+     * permanently lost the ability to undo bytes it wrote.
+     *
+     * The mechanism is a granularity mismatch, not a lock. Process B reads the
+     * ledger before A persists, so B's snapshot holds none of A's claims. B then
+     * reads the vendor file, which by now holds A's entries, and classifies them
+     * as foreign — CORRECTLY, since nothing B can see claims them — so they never
+     * reach `projected.records`. The merge decided per entry; the write then
+     * replaced the whole scope. B left A's bytes alone and erased A's claim in the
+     * same breath. Keying the drop to what the caller examined is what makes the
+     * two agree.
+     *
+     * Deliberately NOT one write per entry: that shape preserves the same claims,
+     * but measured 99 writes per init instead of 6 (p50 61.5 ms each, 69x the
+     * ledger phase) and opened a contention cliff — 17 of 48 scopes failing at
+     * eight concurrent inits against 0 of 48 today. This keeps one write per scope.
+     *
+     * Still serialised against concurrent calls on this instance, and still NOT a
+     * fix for the orphan window above it: `engine.ts` writes the vendor file
+     * before it reaches this method, so a persist that throws — or a crash in
+     * between — leaves bytes no record claims. That is a different defect with a
+     * different fix, and it is open.
+     */
+    update(scope: ProjectionLedgerScope, records: readonly ProjectionLedgerRecord[], examined: readonly string[]): Promise<void>;
+    /**
+     * Replaces ONE entry's record inside one scope, reading the current document
+     * INSIDE the queue.
+     *
+     * The granularity is the point. A caller that read the ledger, decided, and
+     * then handed `update` a whole replacement set for the scope would resurrect
+     * every claim another writer legitimately dropped in between — brambo would
+     * then claim a path it does not own, which on the materialisation path is a
+     * delete authority. Only the named entry moves here; every sibling claim is
+     * whatever the document says at the moment of the write.
+     *
+     * `record === undefined` drops the entry instead of replacing it.
+     */
+    updateEntry(scope: ProjectionLedgerScope, entryId: string, record: ProjectionLedgerRecord | undefined): Promise<void>;
+    /**
+     * Replaces the WHOLE document with whatever `select` returns for the document
+     * as it is INSIDE the queue.
+     *
+     * This is the one write that does not merge, and it exists for exactly one
+     * caller: the user-named `repair` remediation, which is how a ledger holding
+     * records brambo cannot read stops being a state with no exit. Nothing else may
+     * use it — `update` is the merging write every projection performs, and its
+     * refusal to overwrite an unreadable ledger is a load-bearing guarantee that
+     * this method deliberately does not have. `test/guard.test.ts` pins the caller
+     * list, because a second one would silently reintroduce the orphan-every-claim
+     * failure Story 2.8 declared terminal.
+     *
+     * `select` runs INSIDE the queue and is handed the read the write will be
+     * based on. A caller that read the document itself and passed the result would
+     * destroy every claim written in between — with no merge to save it, which is
+     * exactly what makes this method the dangerous one. It may throw to abort the
+     * write, which is how `repair` refuses when the document moved under it.
+     */
+    rewriteAll(authority: typeof LEDGER_REPAIR_AUTHORITY, select: (read: ProjectionLedgerRead) => readonly ProjectionLedgerRecord[]): Promise<void>;
+}