@3fn/core 14.0.0 → 15.0.0

package/dist/cli/sync/NameContract.d.ts

@@ -0,0 +1,169 @@
+/**
+ * The name contract (Req 5A) and the type contract (DD11) — `sync`'s one report
+ * about the consumer's token language. It REPORTS and NEVER WRITES (Req 5A.2 /
+ * 5.8): nothing here adds, aliases, or defaults a token into the consumer's tier.
+ *
+ * Spec 123 Task 6 (design.md § "C7" name contract; DD10, DD11, DD17; P1 ruled YES).
+ *
+ * - **Source**: `<package>/dist/name-contract.json`, built from the COMPILED web
+ *   surface by `scripts/build-name-contract.ts` (never from src at sync time).
+ * - **Check**: referenced names, tier-filtered — **semantic ALWAYS · primitive YES ·
+ *   component NEVER** — minus the custom properties DEFINED in the consumer's
+ *   generated web token CSS (`<outputDir>/DesignTokens.web.css`, the output
+ *   directory from her config).
+ * - **No generated web output → `cannot check`**, never a clean report.
+ * - A component carrying an `uncovered` dynamic site gets a standing
+ *   "not checked" line — never silently clean (R26.8).
+ * - Scope: web-surface names only (Task 3.5's decision record — native out).
+ */
+export declare const NAME_CONTRACT_REL = "dist/name-contract.json";
+export declare const GENERATED_WEB_CSS = "DesignTokens.web.css";
+export type ContractTier = 'semantic' | 'primitive' | 'component';
+/** P1 (Peter, 2026-09-26). Applied here AND at build — the check never trusts the file's filtering. */
+export declare const TIER_FILTER: Record<ContractTier, boolean>;
+export interface ContractName {
+    name: string;
+    tier: ContractTier;
+    token: string;
+    part?: string;
+    value: string;
+    usedBy: string[];
+    declaredUse: string;
+}
+export interface NameContractFile {
+    schemaVersion: number;
+    referencedNames: ContractName[];
+    notChecked?: Array<{
+        component: string;
+        site: string;
+    }>;
+    typeContract?: {
+        hash: string;
+        members: string[];
+    };
+}
+/** Row "name contract — missing (A9)". */
+export declare function missingTokenMessage(a: {
+    name: string;
+    declaredUse: string;
+    components: string[];
+    tierPath: string;
+    value: string;
+    dpToken: string;
+}): string;
+/** Row "name contract — cannot check". */
+export declare function cannotCheckMessage(outputDir: string): string;
+/** Row "type contract changed". DD11's no-member-diff case fills the parenthetical with its residual string. */
+export declare function typeContractChangedMessage(removed: string[], added: string[]): string;
+/** DD11 residual, verbatim: a cosmetic `.d.ts` change moves the hash with no member diff. */
+export declare const NO_MEMBER_CHANGES = "no member changes detected \u2014 shape or formatting changed";
+/** Standing line for a component with an `uncovered` dynamic site (tasks.md Task 6). */
+export declare function notCheckedMessage(component: string): string;
+/** Clean — what it establishes (design C7 § "What a clean report establishes"). */
+export declare function cleanMessage(outputDir: string): string;
+/** Req 5A.4 / R26.8 — what a clean report does NOT establish. Printed with every checked report. */
+export declare const SCOPE_MESSAGE = "(A clean name contract does not establish that your values suit the components. DesignerPunk's component-tier tokens and the iOS/Android surfaces are not checked.)";
+export declare function contractMissingMessage(pkgRoot: string): string;
+export declare function configUnreadableMessage(error: string): string;
+export declare function loadNameContract(pkgRoot: string): NameContractFile | null;
+/** The package's type-contract hash (DD11) for the manifest's `contractHash`; '' when the package ships no contract. */
+export declare function readContractHash(pkgRoot: string): string;
+/** Custom properties DEFINED in the consumer's generated web token CSS; `null` = no output. */
+export declare function readPresentNames(outputDir: string): Set<string> | null;
+export interface NameContractContext {
+    /** Display form of the generated output directory (e.g. `dist`). */
+    outputDirDisplay: string;
+    /** Display form of the consumer's semantic tier (e.g. `src/tokens/semantic/`). */
+    semanticTierPath: string;
+    /** Display form of the consumer's primitive tier (e.g. `src/tokens/`). */
+    primitiveTierPath: string;
+}
+export interface NameContractResult {
+    status: 'cannot-check' | 'clean' | 'missing';
+    missing: ContractName[];
+    notChecked: string[];
+    lines: string[];
+}
+export declare function checkNameContract(contract: NameContractFile, present: Set<string> | null, ctx: NameContractContext): NameContractResult;
+export declare function diffMembers(before: string[], after: string[]): {
+    removed: string[];
+    added: string[];
+};
+/**
+ * Compare a recorded type contract with the installed one. `null` when unchanged,
+ * or when nothing was recorded yet (no baseline — the first recording is not a change).
+ */
+export declare function checkTypeContract(recorded: {
+    hash: string;
+    members: string[];
+} | null, current: {
+    hash: string;
+    members: string[];
+}): string | null;
+/** Why there is no baseline (Peter's ruling: a clear "no baseline" outcome). */
+export type NoBaselineCause = {
+    kind: 'no-recorded-hash';
+} | {
+    kind: 'predates-contract';
+    version: string;
+};
+/** Why the change cannot be itemized (a `cannot tell`, never clean). */
+export type TypeCannotTellCause = {
+    kind: 'fetch-failed';
+    version: string;
+} | {
+    kind: 'baseline-mismatch';
+    version: string;
+};
+/** PROPOSED catalog row "type contract — no baseline" (no design row yet; routed as an erratum). */
+export declare function typeContractNoBaselineMessage(cause: NoBaselineCause): string;
+/** PROPOSED catalog row "type contract — cannot tell" (no design row yet; routed as an erratum). */
+export declare function typeContractCannotTellMessage(cause: TypeCannotTellCause): string;
+/** What fetching the previous version's contract produced. */
+export type PreviousContract = {
+    kind: 'ok';
+    typeContract: {
+        hash: string;
+        members: string[];
+    };
+} | {
+    kind: 'fetch-failed';
+} | {
+    kind: 'no-contract';
+};
+export type TypeContractOutcome = {
+    kind: 'unavailable';
+    lines: string[];
+} | {
+    kind: 'unchanged';
+    lines: string[];
+} | {
+    kind: 'no-baseline';
+    cause: NoBaselineCause;
+    lines: string[];
+} | {
+    kind: 'changed';
+    removed: string[];
+    added: string[];
+    lines: string[];
+} | {
+    kind: 'cannot-tell';
+    cause: TypeCannotTellCause;
+    lines: string[];
+};
+/**
+ * Assess the type contract for one `sync` run. `fetchPrevious` is called ONLY when the
+ * recorded hash is present and differs from the installed one.
+ */
+export declare function assessTypeContract(a: {
+    recordedHash: string;
+    recordedVersion: string;
+    current: {
+        hash: string;
+        members: string[];
+    } | undefined;
+    fetchPrevious: (version: string) => PreviousContract;
+}): TypeContractOutcome;
+/** Read a fetched package root's contract (`no-contract` when that version predates it). */
+export declare function previousContractAt(root: string | null): PreviousContract;
+//# sourceMappingURL=NameContract.d.ts.map

package/dist/cli/sync/NameContract.js

@@ -0,0 +1,246 @@
+"use strict";
+/**
+ * The name contract (Req 5A) and the type contract (DD11) — `sync`'s one report
+ * about the consumer's token language. It REPORTS and NEVER WRITES (Req 5A.2 /
+ * 5.8): nothing here adds, aliases, or defaults a token into the consumer's tier.
+ *
+ * Spec 123 Task 6 (design.md § "C7" name contract; DD10, DD11, DD17; P1 ruled YES).
+ *
+ * - **Source**: `<package>/dist/name-contract.json`, built from the COMPILED web
+ *   surface by `scripts/build-name-contract.ts` (never from src at sync time).
+ * - **Check**: referenced names, tier-filtered — **semantic ALWAYS · primitive YES ·
+ *   component NEVER** — minus the custom properties DEFINED in the consumer's
+ *   generated web token CSS (`<outputDir>/DesignTokens.web.css`, the output
+ *   directory from her config).
+ * - **No generated web output → `cannot check`**, never a clean report.
+ * - A component carrying an `uncovered` dynamic site gets a standing
+ *   "not checked" line — never silently clean (R26.8).
+ * - Scope: web-surface names only (Task 3.5's decision record — native out).
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SCOPE_MESSAGE = exports.NO_MEMBER_CHANGES = exports.TIER_FILTER = exports.GENERATED_WEB_CSS = exports.NAME_CONTRACT_REL = void 0;
+exports.missingTokenMessage = missingTokenMessage;
+exports.cannotCheckMessage = cannotCheckMessage;
+exports.typeContractChangedMessage = typeContractChangedMessage;
+exports.notCheckedMessage = notCheckedMessage;
+exports.cleanMessage = cleanMessage;
+exports.contractMissingMessage = contractMissingMessage;
+exports.configUnreadableMessage = configUnreadableMessage;
+exports.loadNameContract = loadNameContract;
+exports.readContractHash = readContractHash;
+exports.readPresentNames = readPresentNames;
+exports.checkNameContract = checkNameContract;
+exports.diffMembers = diffMembers;
+exports.checkTypeContract = checkTypeContract;
+exports.typeContractNoBaselineMessage = typeContractNoBaselineMessage;
+exports.typeContractCannotTellMessage = typeContractCannotTellMessage;
+exports.assessTypeContract = assessTypeContract;
+exports.previousContractAt = previousContractAt;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+exports.NAME_CONTRACT_REL = 'dist/name-contract.json';
+exports.GENERATED_WEB_CSS = 'DesignTokens.web.css';
+/** P1 (Peter, 2026-09-26). Applied here AND at build — the check never trusts the file's filtering. */
+exports.TIER_FILTER = {
+    semantic: true, // ALWAYS
+    primitive: true, // YES (P1)
+    component: false, // NEVER (DD17)
+};
+// ---------------------------------------------------------------------------
+// Catalog rows (design.md § "Error Handling") — exact strings
+// ---------------------------------------------------------------------------
+/** Row "name contract — missing (A9)". */
+function missingTokenMessage(a) {
+    return (`components now expect token '${a.name}' — ${a.declaredUse} (used by ${a.components.join(', ')}). ` +
+        `Add it to your set in ${a.tierPath}. Your tokens are yours; DesignerPunk never adds to them. ` +
+        `DesignerPunk's value, for reference: ${a.value} ('${a.dpToken}' in DesignerPunk's language). ` +
+        `See: install doc § "When sync reports a missing token".`);
+}
+/** Row "name contract — cannot check". */
+function cannotCheckMessage(outputDir) {
+    return `cannot check the name contract — no generated web token output found at ${outputDir}. Run 'npx designerpunk generate' first. (This is not a clean report.)`;
+}
+/** Row "type contract changed". DD11's no-member-diff case fills the parenthetical with its residual string. */
+function typeContractChangedMessage(removed, added) {
+    const detail = removed.length === 0 && added.length === 0
+        ? exports.NO_MEMBER_CHANGES
+        : `removed: ${removed.length ? removed.join(', ') : 'none'}; added: ${added.length ? added.join(', ') : 'none'}`;
+    return `the token type contract changed (${detail}). Run 'npx tsc --noEmit' — fix each file it names; removed members are listed above.`;
+}
+/** DD11 residual, verbatim: a cosmetic `.d.ts` change moves the hash with no member diff. */
+exports.NO_MEMBER_CHANGES = 'no member changes detected — shape or formatting changed';
+// ---------------------------------------------------------------------------
+// Strings authored at Task 6 (no catalog row) — pinned by sync.name-contract.test.ts
+// ---------------------------------------------------------------------------
+/** Standing line for a component with an `uncovered` dynamic site (tasks.md Task 6). */
+function notCheckedMessage(component) {
+    return `not checked: ${component} builds token names dynamically`;
+}
+/** Clean — what it establishes (design C7 § "What a clean report establishes"). */
+function cleanMessage(outputDir) {
+    return `name contract: clean — every semantic and primitive token name DesignerPunk's web components reference is defined in your generated web CSS at ${outputDir}.`;
+}
+/** Req 5A.4 / R26.8 — what a clean report does NOT establish. Printed with every checked report. */
+exports.SCOPE_MESSAGE = "(A clean name contract does not establish that your values suit the components. DesignerPunk's component-tier tokens and the iOS/Android surfaces are not checked.)";
+function contractMissingMessage(pkgRoot) {
+    return `cannot check the name contract — the installed package has no ${exports.NAME_CONTRACT_REL} (${pkgRoot}). (This is not a clean report.)`;
+}
+function configUnreadableMessage(error) {
+    return `cannot check the name contract — designerpunk.config.ts could not be loaded (${error}), so the generated output directory is unknown. (This is not a clean report.)`;
+}
+// ---------------------------------------------------------------------------
+// The check
+// ---------------------------------------------------------------------------
+function loadNameContract(pkgRoot) {
+    const p = path.join(pkgRoot, exports.NAME_CONTRACT_REL);
+    if (!fs.existsSync(p))
+        return null;
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+}
+/** The package's type-contract hash (DD11) for the manifest's `contractHash`; '' when the package ships no contract. */
+function readContractHash(pkgRoot) {
+    try {
+        return loadNameContract(pkgRoot)?.typeContract?.hash ?? '';
+    }
+    catch {
+        return '';
+    }
+}
+/** Custom properties DEFINED in the consumer's generated web token CSS; `null` = no output. */
+function readPresentNames(outputDir) {
+    const p = path.join(outputDir, exports.GENERATED_WEB_CSS);
+    if (!fs.existsSync(p))
+        return null;
+    const css = fs.readFileSync(p, 'utf8').replace(/\/\*[\s\S]*?\*\//g, '');
+    const out = new Set();
+    for (const m of css.matchAll(/(--[A-Za-z_][A-Za-z0-9_-]*)\s*:/g))
+        out.add(m[1]);
+    return out;
+}
+function checkNameContract(contract, present, ctx) {
+    const notChecked = [...new Set((contract.notChecked ?? []).map((n) => n.component))].sort();
+    const notCheckedLines = notChecked.map(notCheckedMessage);
+    if (present === null) {
+        return { status: 'cannot-check', missing: [], notChecked, lines: [cannotCheckMessage(ctx.outputDirDisplay), ...notCheckedLines] };
+    }
+    const missing = contract.referencedNames.filter((r) => exports.TIER_FILTER[r.tier] === true && !present.has(r.name));
+    const lines = missing.map((r) => missingTokenMessage({
+        name: r.name,
+        declaredUse: r.declaredUse,
+        components: r.usedBy,
+        tierPath: r.tier === 'primitive' ? ctx.primitiveTierPath : ctx.semanticTierPath,
+        value: r.value,
+        dpToken: r.token,
+    }));
+    if (missing.length === 0)
+        lines.push(cleanMessage(ctx.outputDirDisplay));
+    lines.push(...notCheckedLines, exports.SCOPE_MESSAGE);
+    return { status: missing.length ? 'missing' : 'clean', missing, notChecked, lines };
+}
+// ---------------------------------------------------------------------------
+// The type contract (DD11)
+// ---------------------------------------------------------------------------
+function diffMembers(before, after) {
+    const a = new Set(after);
+    const b = new Set(before);
+    return { removed: before.filter((m) => !a.has(m)), added: after.filter((m) => !b.has(m)) };
+}
+/**
+ * Compare a recorded type contract with the installed one. `null` when unchanged,
+ * or when nothing was recorded yet (no baseline — the first recording is not a change).
+ */
+function checkTypeContract(recorded, current) {
+    if (!recorded || !recorded.hash || recorded.hash === current.hash)
+        return null;
+    const { removed, added } = diffMembers(recorded.members, current.members);
+    return typeContractChangedMessage(removed, added);
+}
+/** PROPOSED catalog row "type contract — no baseline" (no design row yet; routed as an erratum). */
+function typeContractNoBaselineMessage(cause) {
+    const why = cause.kind === 'no-recorded-hash'
+        ? 'your manifest records no contractHash'
+        : `version ${cause.version} predates DesignerPunk's name contract (it ships no ${exports.NAME_CONTRACT_REL})`;
+    return `no baseline to compare the token type contract against — ${why}. sync records the installed contract as the baseline the next time it writes the manifest.`;
+}
+/** PROPOSED catalog row "type contract — cannot tell" (no design row yet; routed as an erratum). */
+function typeContractCannotTellMessage(cause) {
+    const why = cause.kind === 'fetch-failed'
+        ? `the package content for version ${cause.version} could not be retrieved`
+        : `version ${cause.version}'s contract does not match the contractHash your manifest recorded`;
+    return `cannot tell what changed in the token type contract — ${why}. It did change: run 'npx tsc --noEmit' — fix each file it names. (This is not a clean report.)`;
+}
+/**
+ * Assess the type contract for one `sync` run. `fetchPrevious` is called ONLY when the
+ * recorded hash is present and differs from the installed one.
+ */
+function assessTypeContract(a) {
+    if (!a.current)
+        return { kind: 'unavailable', lines: [] };
+    if (!a.recordedHash) {
+        const cause = { kind: 'no-recorded-hash' };
+        return { kind: 'no-baseline', cause, lines: [typeContractNoBaselineMessage(cause)] };
+    }
+    if (a.recordedHash === a.current.hash)
+        return { kind: 'unchanged', lines: [] };
+    const prev = a.fetchPrevious(a.recordedVersion);
+    if (prev.kind === 'fetch-failed') {
+        const cause = { kind: 'fetch-failed', version: a.recordedVersion };
+        return { kind: 'cannot-tell', cause, lines: [typeContractCannotTellMessage(cause)] };
+    }
+    if (prev.kind === 'no-contract') {
+        const cause = { kind: 'predates-contract', version: a.recordedVersion };
+        return { kind: 'no-baseline', cause, lines: [typeContractNoBaselineMessage(cause)] };
+    }
+    if (prev.typeContract.hash !== a.recordedHash) {
+        const cause = { kind: 'baseline-mismatch', version: a.recordedVersion };
+        return { kind: 'cannot-tell', cause, lines: [typeContractCannotTellMessage(cause)] };
+    }
+    const { removed, added } = diffMembers(prev.typeContract.members, a.current.members);
+    return { kind: 'changed', removed, added, lines: [typeContractChangedMessage(removed, added)] };
+}
+/** Read a fetched package root's contract (`no-contract` when that version predates it). */
+function previousContractAt(root) {
+    if (!root)
+        return { kind: 'fetch-failed' };
+    try {
+        const c = loadNameContract(root);
+        return c?.typeContract ? { kind: 'ok', typeContract: c.typeContract } : { kind: 'no-contract' };
+    }
+    catch {
+        return { kind: 'fetch-failed' };
+    }
+}
+//# sourceMappingURL=NameContract.js.map

package/dist/cli/sync/RegionGrain.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Region grain — extraction and splicing of a DesignerPunk-managed marker
+ * region inside a consumer-owned text file (Spec 123 Task 16.4; design.md
+ * § "C7. `sync` — managed set, grains, classification, pruning, migration",
+ * row `CLAUDE.md` / `.gitignore` — "marker region"; § "THE NAMESPACE RULE,
+ * uniform across all three grains" — "prefix for keys and files, markers
+ * for text").
+ *
+ * Pure functions over strings — no filesystem access. A caller (`attach`,
+ * `sync`) reads the file, calls `spliceRegion`, and only writes when the
+ * result is `ok: true`. This module never throws and never performs I/O:
+ * a missing or unmatched marker pair is a normal (non-exceptional) result
+ * carrying the loud-failure catalog string (`errorCatalog.ts`,
+ * `managedRegionMarkersMissingMessage`).
+ *
+ * **Grain, defined**:
+ *  - The region is the text strictly between the END of the begin-marker's
+ *    own line and the START of the end-marker's own line. The region's
+ *    surrounding marker lines are themselves part of "outside" bytes that
+ *    round-trip unchanged on a successful splice (only the inner content
+ *    is replaced).
+ *  - **First pair wins** (defined nested/duplicate-marker behavior, per
+ *    Task 16.4's brief): extraction matches the FIRST `begin` marker and
+ *    the FIRST `end` marker that follows it. A second `begin`/`end` pair
+ *    appearing later in the file is left untouched, inside the returned
+ *    `after` bytes — it is never read as a second region. A `begin`
+ *    appearing again INSIDE the matched region (before the matched `end`)
+ *    is treated as ordinary region content, not as a nested marker.
+ *  - An absent `begin`, an absent `end`, or an `end` with no preceding
+ *    `begin` are all the same outcome: "missing markers".
+ *  - **CRLF/LF**: the end-of-line style used for the two newlines the
+ *    splice introduces (after `begin`, before `end`) is detected from the
+ *    file's OUTSIDE bytes (the text before the matched `begin` plus the
+ *    text from the matched `end` onward) — never from the region being
+ *    replaced — so re-splicing is idempotent and never flips a CRLF file
+ *    to LF (or vice versa) by way of its own prior contents.
+ */
+/** A begin/end marker PAIR, as literal line text (no trailing newline). */
+export interface RegionMarkers {
+    /** The exact text of the region's opening marker line, e.g. `<!-- designerpunk:managed:begin -->`. */
+    begin: string;
+    /** The exact text of the region's closing marker line, e.g. `<!-- designerpunk:managed:end -->`. */
+    end: string;
+}
+/** A comment syntax a target file's language uses for a single marker line. */
+export interface CommentSyntax {
+    /** Opens the comment (and the whole marker line), e.g. `<!--` or `#`. */
+    open: string;
+    /** Closes the comment, when the syntax wraps (e.g. `-->`). Omit for line comments (e.g. `#`). */
+    close?: string;
+}
+/** `CLAUDE.md`'s comment syntax (HTML-style wrapping comment). */
+export declare const CLAUDE_MD_COMMENT: CommentSyntax;
+/** `.gitignore`'s comment syntax (line comment, no closer). */
+export declare const GITIGNORE_COMMENT: CommentSyntax;
+/**
+ * Build the begin/end marker pair for a given comment syntax and region
+ * label (default `managed`, the one DesignerPunk region today — C7 names
+ * `CLAUDE.md` and `.gitignore` as the two text-grain managed surfaces; a
+ * second label is available for a future second region in the same file).
+ */
+export declare function regionMarkers(syntax: CommentSyntax, label?: string): RegionMarkers;
+export type RegionExtraction = {
+    found: true;
+    before: string;
+    region: string;
+    after: string;
+} | {
+    found: false;
+};
+export type SpliceResult = {
+    ok: true;
+    text: string;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Extract the managed region from `text`. Returns `{ found: false }` on a
+ * missing or unmatched marker pair — never throws.
+ *
+ * **Invariant**: on a match, `before + region + after === text` exactly —
+ * `region` carries the content between the begin-marker's line and the
+ * end-marker's line, INCLUDING the eol that terminates it (so the split
+ * reassembles byte-for-byte with no extra bookkeeping by the caller).
+ */
+export declare function extractRegion(text: string, markers: RegionMarkers): RegionExtraction;
+/**
+ * Replace the managed region's contents with `newContents`. Bytes outside
+ * the matched marker pair are byte-identical to `text` on success.
+ *
+ * On a missing or unmatched marker pair, returns `{ ok: false, message }`
+ * carrying the exact loud-failure catalog string for `file` — the caller
+ * must not write in that case (this function never does I/O itself).
+ */
+export declare function spliceRegion(text: string, markers: RegionMarkers, newContents: string, file: string): SpliceResult;
+/**
+ * The region content in the ONE form `attach` records and `sync` compares (the
+ * manifest's region-entry hash is the sha256 of this string): line endings
+ * normalized to LF, then ONE trailing line ending stripped — exactly the body
+ * `spliceRegion` writes between the markers. So a region extracted from disk
+ * (`extractRegion(…).region`, which carries its own trailing eol, in the file's
+ * eol style) and the package's emitted contents normalize to the same string
+ * when they hold the same lines, on a CRLF file as on an LF one.
+ */
+export declare function normalizeRegionContent(contents: string): string;
+/** The full text of a file that holds only the managed region (the create case). */
+export declare function wrapRegion(markers: RegionMarkers, newContents: string): string;
+/**
+ * Append a managed region to a file that has NONE yet (the first `attach` into a
+ * consumer's existing `CLAUDE.md`). Every existing byte is kept, in place, as the
+ * prefix of the result; the region goes after it, separated by one blank line, in
+ * the file's own line-ending style. Callers use this only when the manifest
+ * records no region for the file — a recorded region whose markers are gone is
+ * the catalog's "markers missing" case, never re-appended.
+ */
+export declare function appendRegion(text: string, markers: RegionMarkers, newContents: string): string;
+//# sourceMappingURL=RegionGrain.d.ts.map