@3fn/core 14.0.0 → 15.0.0

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

@@ -1,16 +1,38 @@
 /**
- * Classify files by comparing package, project, and manifest state.
+ * File- and region-grain classification — package side vs consumer current vs
+ * manifest.
  *
- * @see Spec 111 — Requirement 2
+ * Spec 123 Task 5.4 (design.md § "C7" Classification), re-scoped at Task 16.5.
+ * Reused from Spec 111's three-way comparison; changed in WHAT is managed:
+ *  - only entries of ONE origin under the MANAGED roots are classified. Since
+ *    Task 16.5 `sync` passes `origin: 'generated'` and the agent-layer roots the
+ *    package emits for the manifest's `attachedTargets` (C7: "the package side of
+ *    the generated surfaces is freshly generated, by `emitConsumer`"). The
+ *    release-1 copy roots are no longer managed: a `copy` entry is a LEGACY COPY,
+ *    reported by `Migration.ts`, and is never classified here — not even when a
+ *    generated file lands on the same path (`.kiro/agents/<a>.json` on Kiro),
+ *    which is skipped, never a `conflict`;
+ *  - `deleted-by-you`: a manifest entry exists and the project lacks the file →
+ *    reported, never re-added (`--restore <path>` re-adds);
+ *  - `untracked-new`: no manifest entry AND no project file, for a target with
+ *    nothing recorded yet (the first-sync case) → reported, NEVER APPLIED on a
+ *    generated surface ("Re-adding requires `attach`, which records it");
+ *  - `removed` is scoped to entries under currently managed roots (D-B6) —
+ *    de-managed entries are PRUNED before classification, never `removed`.
+ *
+ * The default `origin` stays `'copy'`, so a caller passing no options gets the
+ * U1 behavior unchanged.
+ *
+ * @see Spec 111 — Requirement 2; Spec 123 design.md § "C7"
  */
 import type { ScannedFile } from './FileScanner';
-import type { SyncManifest } from './Manifest';
 import type { IgnoreFilter } from './IgnoreFilter';
-export type FileClassification = 'new' | 'updated-safe' | 'conflict' | 'unchanged' | 'removed';
+import type { ManifestEntry, ManifestOrigin } from './Manifest';
+import type { RegionMarkers } from './RegionGrain';
+export type FileClassification = 'new' | 'updated-safe' | 'conflict' | 'unchanged' | 'removed' | 'deleted-by-you' | 'untracked-new';
 export interface ClassifiedFile {
     relativePath: string;
     classification: FileClassification;
-    tier: 'governance' | 'source';
     packageHash: string;
     projectHash?: string;
     manifestHash?: string;
@@ -22,6 +44,48 @@ export interface ClassificationResult {
     conflicts: ClassifiedFile[];
     unchanged: ClassifiedFile[];
     removed: ClassifiedFile[];
+    deletedByYou: ClassifiedFile[];
+    /** No manifest entry and no project file, for a surface with nothing recorded yet — REPORTED, NEVER APPLIED (C7). */
+    untrackedNew: ClassifiedFile[];
+    /** Unrecorded project files byte-identical to the package's — adopted into the manifest on apply. */
+    adoptable: ClassifiedFile[];
+    /** Manifest entries whose package file AND project file are both gone — dropped on apply. */
+    dropEntries: string[];
+}
+export declare function emptyClassification(): ClassificationResult;
+export interface ClassifyOptions {
+    /** The entry origin this pass manages (default `'copy'` — the U1 behavior). */
+    origin?: ManifestOrigin;
+    /**
+     * A package path with no entry and no project file is `untracked-new` (never
+     * applied) when this returns true, else `new`. Default: never untracked.
+     */
+    untracked?: (relativePath: string) => boolean;
 }
-export declare function classifyFiles(packageFiles: ScannedFile[], projectFiles: ScannedFile[], manifest: SyncManifest | null, ignore: IgnoreFilter): ClassificationResult;
+/** The copy roots this manifest actually manages (≥1 `origin: 'copy'` file entry under the root). */
+export declare function managedCopyRoots(entries: Record<string, ManifestEntry>): string[];
+export declare function classifyFiles(packageFiles: ScannedFile[], projectFiles: ScannedFile[], entries: Record<string, ManifestEntry>, ignore: IgnoreFilter, managedRoots: string[], options?: ClassifyOptions): ClassificationResult;
+/** The manifest id of a file's managed region (`attach` records it). */
+export declare function regionEntryId(file: string): string;
+export type RegionClassification = {
+    kind: 'unchanged' | 'updated-safe' | 'conflict' | 'new' | 'untracked-new' | 'deleted-by-you' | 'adoptable';
+} | {
+    kind: 'markers-missing';
+};
+/**
+ * Classify one managed region. `projectText` is the file's current text
+ * (`undefined` when the file is absent); `packageContents` is the region the
+ * package emits; `entry` is the manifest's record of it. Region hashes are over
+ * `normalizeRegionContent` (the form `attach` records).
+ *
+ *  - recorded, file absent → `deleted-by-you`;
+ *  - recorded, markers gone → `markers-missing` (the catalog string; no write);
+ *  - recorded, region == package → `unchanged`; == recorded → `updated-safe`; else
+ *    `conflict` (the catalog's "edited inside" row);
+ *  - unrecorded, region present → `adoptable` when equal to the package's, else
+ *    `conflict`;
+ *  - unrecorded, no region → `untracked-new` (or `new` when the target already has
+ *    recorded surfaces: `untracked` is false).
+ */
+export declare function classifyRegion(projectText: string | undefined, markers: RegionMarkers, packageContents: string, entry: ManifestEntry | undefined, untracked: boolean): RegionClassification;
 //# sourceMappingURL=Classifier.d.ts.map

package/dist/cli/sync/Classifier.js

@@ -1,103 +1,142 @@
 "use strict";
 /**
- * Classify files by comparing package, project, and manifest state.
+ * File- and region-grain classification — package side vs consumer current vs
+ * manifest.
  *
- * @see Spec 111 — Requirement 2
+ * Spec 123 Task 5.4 (design.md § "C7" Classification), re-scoped at Task 16.5.
+ * Reused from Spec 111's three-way comparison; changed in WHAT is managed:
+ *  - only entries of ONE origin under the MANAGED roots are classified. Since
+ *    Task 16.5 `sync` passes `origin: 'generated'` and the agent-layer roots the
+ *    package emits for the manifest's `attachedTargets` (C7: "the package side of
+ *    the generated surfaces is freshly generated, by `emitConsumer`"). The
+ *    release-1 copy roots are no longer managed: a `copy` entry is a LEGACY COPY,
+ *    reported by `Migration.ts`, and is never classified here — not even when a
+ *    generated file lands on the same path (`.kiro/agents/<a>.json` on Kiro),
+ *    which is skipped, never a `conflict`;
+ *  - `deleted-by-you`: a manifest entry exists and the project lacks the file →
+ *    reported, never re-added (`--restore <path>` re-adds);
+ *  - `untracked-new`: no manifest entry AND no project file, for a target with
+ *    nothing recorded yet (the first-sync case) → reported, NEVER APPLIED on a
+ *    generated surface ("Re-adding requires `attach`, which records it");
+ *  - `removed` is scoped to entries under currently managed roots (D-B6) —
+ *    de-managed entries are PRUNED before classification, never `removed`.
+ *
+ * The default `origin` stays `'copy'`, so a caller passing no options gets the
+ * U1 behavior unchanged.
+ *
+ * @see Spec 111 — Requirement 2; Spec 123 design.md § "C7"
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.emptyClassification = emptyClassification;
+exports.managedCopyRoots = managedCopyRoots;
 exports.classifyFiles = classifyFiles;
-function classifyFiles(packageFiles, projectFiles, manifest, ignore) {
-    const result = {
-        new: [],
-        updatedSafe: [],
-        conflicts: [],
-        unchanged: [],
-        removed: [],
-    };
-    // Index project files by relative path for O(1) lookup
-    const projectMap = new Map();
-    for (const f of projectFiles) {
-        projectMap.set(f.relativePath, f);
-    }
-    const manifestFiles = manifest?.files ?? {};
-    // Iterate package files only (package-direction guarantee)
-    for (const pkgFile of packageFiles) {
-        if (ignore.isIgnored(pkgFile.relativePath))
+exports.regionEntryId = regionEntryId;
+exports.classifyRegion = classifyRegion;
+const Manifest_1 = require("./Manifest");
+const RegionGrain_1 = require("./RegionGrain");
+const FileScanner_1 = require("./FileScanner");
+function emptyClassification() {
+    return { new: [], updatedSafe: [], conflicts: [], unchanged: [], removed: [], deletedByYou: [], untrackedNew: [], adoptable: [], dropEntries: [] };
+}
+/** The copy roots this manifest actually manages (≥1 `origin: 'copy'` file entry under the root). */
+function managedCopyRoots(entries) {
+    return Manifest_1.COPY_ROOTS.filter((root) => Object.entries(entries).some(([key, e]) => e.origin === 'copy' && e.grain === 'file' && (0, Manifest_1.isUnder)(key, root)));
+}
+function classifyFiles(packageFiles, projectFiles, entries, ignore, managedRoots, options = {}) {
+    const origin = options.origin ?? 'copy';
+    const result = emptyClassification();
+    const underManaged = (p) => managedRoots.some((r) => (0, Manifest_1.isUnder)(p, r));
+    const projectMap = new Map(projectFiles.map((f) => [f.relativePath, f]));
+    const packageMap = new Map(packageFiles.map((f) => [f.relativePath, f]));
+    // 1. Every recorded entry of this origin under a managed root.
+    for (const [rel, entry] of Object.entries(entries)) {
+        if (entry.grain !== 'file' || entry.origin !== origin || !underManaged(rel))
             continue;
-        const projFile = projectMap.get(pkgFile.relativePath);
-        const manifestEntry = manifestFiles[pkgFile.relativePath];
-        if (!projFile) {
-            // R2 AC1: In package but not in project → New
-            result.new.push({
-                relativePath: pkgFile.relativePath,
-                classification: 'new',
-                tier: pkgFile.tier,
-                packageHash: pkgFile.hash,
-            });
-        }
-        else if (pkgFile.hash === projFile.hash) {
-            // R2 AC4: Package hash equals project hash → Unchanged
-            result.unchanged.push({
-                relativePath: pkgFile.relativePath,
-                classification: 'unchanged',
-                tier: pkgFile.tier,
-                packageHash: pkgFile.hash,
-                projectHash: projFile.hash,
-                manifestHash: manifestEntry?.hash,
-            });
+        if (ignore.isIgnored(rel))
+            continue;
+        const pkg = packageMap.get(rel);
+        const proj = projectMap.get(rel);
+        if (pkg && proj) {
+            if (pkg.hash === proj.hash) {
+                result.unchanged.push({ relativePath: rel, classification: 'unchanged', packageHash: pkg.hash, projectHash: proj.hash, manifestHash: entry.hash });
+            }
+            else if (proj.hash === entry.hash) {
+                result.updatedSafe.push({ relativePath: rel, classification: 'updated-safe', packageHash: pkg.hash, projectHash: proj.hash, manifestHash: entry.hash, reason: 'unchanged by you — package updated' });
+            }
+            else {
+                result.conflicts.push({ relativePath: rel, classification: 'conflict', packageHash: pkg.hash, projectHash: proj.hash, manifestHash: entry.hash, reason: 'locally modified' });
+            }
         }
-        else if (!manifestEntry) {
-            // R2 AC5: No manifest entry + hashes differ → Conflict (first encounter)
-            result.conflicts.push({
-                relativePath: pkgFile.relativePath,
-                classification: 'conflict',
-                tier: pkgFile.tier,
-                packageHash: pkgFile.hash,
-                projectHash: projFile.hash,
-                reason: 'no sync history (first encounter)',
-            });
+        else if (pkg && !proj) {
+            result.deletedByYou.push({ relativePath: rel, classification: 'deleted-by-you', packageHash: pkg.hash, manifestHash: entry.hash });
         }
-        else if (manifestEntry.hash === projFile.hash) {
-            // R2 AC2: Manifest matches project (consumer hasn't edited) + package differs → Updated-safe
-            result.updatedSafe.push({
-                relativePath: pkgFile.relativePath,
-                classification: 'updated-safe',
-                tier: pkgFile.tier,
-                packageHash: pkgFile.hash,
-                projectHash: projFile.hash,
-                manifestHash: manifestEntry.hash,
-                reason: 'unchanged by you — package updated',
-            });
+        else if (!pkg && proj) {
+            result.removed.push({ relativePath: rel, classification: 'removed', packageHash: '', projectHash: proj.hash, manifestHash: entry.hash, reason: 'removed from package' });
         }
         else {
-            // R2 AC3: Manifest differs from project (consumer edited) + package differs → Conflict
-            result.conflicts.push({
-                relativePath: pkgFile.relativePath,
-                classification: 'conflict',
-                tier: pkgFile.tier,
-                packageHash: pkgFile.hash,
-                projectHash: projFile.hash,
-                manifestHash: manifestEntry.hash,
-                reason: 'locally modified',
-            });
+            result.dropEntries.push(rel);
         }
     }
-    // R2 AC6: Files in manifest but not in package → Removed
-    for (const manifestPath of Object.keys(manifestFiles)) {
-        if (ignore.isIgnored(manifestPath))
+    // 2. Package files under a managed root with no manifest entry. A path holding an
+    //    entry of ANOTHER origin (a legacy copy on a generated path) is skipped too.
+    for (const pkg of packageFiles) {
+        const rel = pkg.relativePath;
+        if (!underManaged(rel) || entries[rel] || ignore.isIgnored(rel))
             continue;
-        const inPackage = packageFiles.some(f => f.relativePath === manifestPath);
-        if (!inPackage) {
-            result.removed.push({
-                relativePath: manifestPath,
-                classification: 'removed',
-                tier: manifestFiles[manifestPath].managed ? 'governance' : 'source',
-                packageHash: '',
-                manifestHash: manifestFiles[manifestPath].hash,
-                reason: 'removed from package',
-            });
+        const proj = projectMap.get(rel);
+        if (!proj) {
+            if (options.untracked?.(rel))
+                result.untrackedNew.push({ relativePath: rel, classification: 'untracked-new', packageHash: pkg.hash });
+            else
+                result.new.push({ relativePath: rel, classification: 'new', packageHash: pkg.hash });
+        }
+        else if (proj.hash === pkg.hash) {
+            result.adoptable.push({ relativePath: rel, classification: 'unchanged', packageHash: pkg.hash, projectHash: proj.hash });
+        }
+        else {
+            result.conflicts.push({ relativePath: rel, classification: 'conflict', packageHash: pkg.hash, projectHash: proj.hash, reason: 'no sync history (first encounter)' });
         }
     }
     return result;
 }
+// ---------------------------------------------------------------------------
+// Region grain (Task 16.5; C7 rows `CLAUDE.md` / `.gitignore` — "marker region")
+// ---------------------------------------------------------------------------
+/** The manifest id of a file's managed region (`attach` records it). */
+function regionEntryId(file) {
+    return `${file}#managed`;
+}
+/**
+ * Classify one managed region. `projectText` is the file's current text
+ * (`undefined` when the file is absent); `packageContents` is the region the
+ * package emits; `entry` is the manifest's record of it. Region hashes are over
+ * `normalizeRegionContent` (the form `attach` records).
+ *
+ *  - recorded, file absent → `deleted-by-you`;
+ *  - recorded, markers gone → `markers-missing` (the catalog string; no write);
+ *  - recorded, region == package → `unchanged`; == recorded → `updated-safe`; else
+ *    `conflict` (the catalog's "edited inside" row);
+ *  - unrecorded, region present → `adoptable` when equal to the package's, else
+ *    `conflict`;
+ *  - unrecorded, no region → `untracked-new` (or `new` when the target already has
+ *    recorded surfaces: `untracked` is false).
+ */
+function classifyRegion(projectText, markers, packageContents, entry, untracked) {
+    const pkg = (0, RegionGrain_1.normalizeRegionContent)(packageContents);
+    const extracted = projectText === undefined ? undefined : (0, RegionGrain_1.extractRegion)(projectText, markers);
+    if (entry) {
+        if (projectText === undefined)
+            return { kind: 'deleted-by-you' };
+        if (!extracted || !extracted.found)
+            return { kind: 'markers-missing' };
+        const proj = (0, RegionGrain_1.normalizeRegionContent)(extracted.region);
+        if (proj === pkg)
+            return { kind: 'unchanged' };
+        return { kind: (0, FileScanner_1.hashBuffer)(proj) === entry.hash ? 'updated-safe' : 'conflict' };
+    }
+    if (extracted && extracted.found) {
+        return { kind: (0, RegionGrain_1.normalizeRegionContent)(extracted.region) === pkg ? 'adoptable' : 'conflict' };
+    }
+    return { kind: untracked ? 'untracked-new' : 'new' };
+}
 //# sourceMappingURL=Classifier.js.map

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

@@ -1,19 +1,28 @@
 /**
- * Scan managed directories and compute SHA-256 content hashes.
+ * Scan directories and compute SHA-256 content hashes.
  *
- * @see Spec 111 — Requirement 1, AC2/AC4/AC5
+ * Spec 123 Task 5.4 re-scope: there is no fixed MANAGED_DIRS list any more.
+ * What `sync` manages is what the manifest recorded (C7's namespace rule), so
+ * callers pass the roots to scan — in U1, the package-copy roots under which the
+ * manifest holds `origin: 'copy'` entries. `src/tokens`, `src/types` and
+ * `src/components/core` are never scanned for reconciliation (Req 5.8; C7's
+ * REMOVED rows). The component-copy MIGRATION reads `src/components/core`
+ * separately (`Migration.ts`), judged against shipped content.
+ *
+ * @see Spec 111 — Requirement 1 (the hashing), Spec 123 design.md § "C7"
  */
-export interface ManagedDir {
-    path: string;
-    tier: 'governance' | 'source';
-    excludeDirs?: string[];
-}
-export declare const MANAGED_DIRS: ManagedDir[];
 export interface ScannedFile {
+    /** Forward-slash, relative to the scan root. */
     relativePath: string;
     absolutePath: string;
     hash: string;
-    tier: 'governance' | 'source';
 }
-export declare function scanFiles(root: string, dirs: ManagedDir[]): ScannedFile[];
+export interface ScanOptions {
+    /** Directory NAMES skipped at any depth (e.g. `__tests__`). */
+    excludeDirs?: string[];
+}
+export declare function hashBuffer(content: Buffer | string): string;
+export declare function hashFile(absolutePath: string): string;
+/** Scan each `relDir` under `root` (missing directories are skipped). */
+export declare function scanFiles(root: string, relDirs: readonly string[], options?: ScanOptions): ScannedFile[];
 //# sourceMappingURL=FileScanner.d.ts.map

package/dist/cli/sync/FileScanner.js

@@ -1,8 +1,16 @@
 "use strict";
 /**
- * Scan managed directories and compute SHA-256 content hashes.
+ * Scan directories and compute SHA-256 content hashes.
  *
- * @see Spec 111 — Requirement 1, AC2/AC4/AC5
+ * Spec 123 Task 5.4 re-scope: there is no fixed MANAGED_DIRS list any more.
+ * What `sync` manages is what the manifest recorded (C7's namespace rule), so
+ * callers pass the roots to scan — in U1, the package-copy roots under which the
+ * manifest holds `origin: 'copy'` entries. `src/tokens`, `src/types` and
+ * `src/components/core` are never scanned for reconciliation (Req 5.8; C7's
+ * REMOVED rows). The component-copy MIGRATION reads `src/components/core`
+ * separately (`Migration.ts`), judged against shipped content.
+ *
+ * @see Spec 111 — Requirement 1 (the hashing), Spec 123 design.md § "C7"
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -38,44 +46,44 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MANAGED_DIRS = void 0;
+exports.hashBuffer = hashBuffer;
+exports.hashFile = hashFile;
 exports.scanFiles = scanFiles;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const crypto = __importStar(require("crypto"));
-exports.MANAGED_DIRS = [
-    { path: '.kiro/steering', tier: 'governance' },
-    { path: 'governance', tier: 'governance' },
-    { path: '.kiro/agents', tier: 'governance' },
-    { path: '.kiro/skills', tier: 'governance' },
-    { path: 'src/tokens', tier: 'source', excludeDirs: ['__tests__'] },
-    { path: 'src/types', tier: 'source', excludeDirs: ['__tests__', 'generated'] },
-    { path: 'src/components/core', tier: 'source', excludeDirs: ['__tests__'] },
-];
-function scanFiles(root, dirs) {
+function hashBuffer(content) {
+    return crypto.createHash('sha256').update(content).digest('hex');
+}
+function hashFile(absolutePath) {
+    return hashBuffer(fs.readFileSync(absolutePath));
+}
+/** Scan each `relDir` under `root` (missing directories are skipped). */
+function scanFiles(root, relDirs, options = {}) {
     const results = [];
-    for (const dir of dirs) {
-        const absDir = path.join(root, dir.path);
-        if (!fs.existsSync(absDir))
+    for (const rel of relDirs) {
+        const absDir = path.join(root, rel);
+        if (!fs.existsSync(absDir) || !fs.statSync(absDir).isDirectory())
             continue;
-        scanRecursive(absDir, root, dir.tier, dir.excludeDirs || [], results);
+        scanRecursive(absDir, root, options.excludeDirs ?? [], results);
     }
     return results;
 }
-function scanRecursive(dir, root, tier, excludeDirs, results) {
-    const entries = fs.readdirSync(dir, { withFileTypes: true });
+function scanRecursive(dir, root, excludeDirs, results) {
+    const entries = fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
     for (const entry of entries) {
+        const absolutePath = path.join(dir, entry.name);
         if (entry.isDirectory()) {
             if (excludeDirs.includes(entry.name))
                 continue;
-            scanRecursive(path.join(dir, entry.name), root, tier, excludeDirs, results);
+            scanRecursive(absolutePath, root, excludeDirs, results);
         }
         else if (entry.isFile()) {
-            const absolutePath = path.join(dir, entry.name);
-            const relativePath = path.relative(root, absolutePath);
-            const content = fs.readFileSync(absolutePath);
-            const hash = crypto.createHash('sha256').update(content).digest('hex');
-            results.push({ relativePath, absolutePath, hash, tier });
+            results.push({
+                relativePath: path.relative(root, absolutePath).split(path.sep).join('/'),
+                absolutePath,
+                hash: hashFile(absolutePath),
+            });
         }
     }
 }

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

@@ -0,0 +1,106 @@
+/**
+ * Key-grain JSON management — Spec 123 Task 5.3 (design.md § "C7" managed-set
+ * rows `.mcp.json`, `.kiro/settings/mcp.json`, `.claude/settings.json`; the
+ * namespace rule; tasks.md § "Open inputs" 5.3 — reading = PARSED VALUES).
+ *
+ * THREE SHAPES:
+ *  - `mcpServers.<key>` in `.kiro/settings/mcp.json` (Kiro) and `.mcp.json` (CC);
+ *  - the `permissions.allow` ARRAY-ENTRY grain in `.claude/settings.json` (CC) —
+ *    an entry's identity IS its string, so the entry is both key and value.
+ *
+ * The reading, as decided:
+ *  - consumer entries survive by PARSED VALUE — we never read or write a key the
+ *    manifest did not record as emitted (a key under our prefix that we never
+ *    emitted is HERS: reported once, never managed or removed);
+ *  - when our keys are unchanged, the file is NOT WRITTEN (zero bytes change);
+ *  - when our keys change, the file is re-serialized with insertion order
+ *    preserved and 2-space indentation — whitespace may normalize on that write
+ *    only.
+ *
+ * The PACKAGE side is the emitters' own output (`shared/mcpConfig/{kiro,cc}.ts`
+ * run against a scratch directory for the manifest's `attachedTargets`), so the
+ * value `sync` compares against is exactly what `init` writes — no second copy
+ * of the emission shape to drift.
+ */
+import type { HarnessTarget, ManifestEntry } from './Manifest';
+export type KeyShape = 'mcpServers' | 'permissionsAllow';
+export interface KeySurface {
+    /** Project-relative, forward-slash. */
+    file: string;
+    target: HarnessTarget;
+    shape: KeyShape;
+}
+/** The three key-grain surfaces (C7 / C8). */
+export declare const KEY_SURFACES: KeySurface[];
+/** The self-label for keys (the namespace rule: prefix for keys and files). */
+export declare const SERVER_KEY_PREFIX = "designerpunk-";
+export declare const ALLOW_ENTRY_PREFIX = "mcp__designerpunk-";
+/**
+ * The key-entry hash. MUST equal `init.ts`'s `ManifestBuilder.recordKey`
+ * (`sha256(JSON.stringify(value))`) — asserted by the init→sync no-op test.
+ */
+export declare function hashKeyValue(value: unknown): string;
+export declare function keyEntryId(file: string, key: string): string;
+export type ProjectKeyRead = {
+    kind: 'absent';
+} | {
+    kind: 'invalid';
+    error: string;
+} | {
+    kind: 'ok';
+    keys: Map<string, unknown>;
+};
+/** Read every key of a surface's shape (consumer keys included — classification filters). */
+export declare function readProjectKeys(projectRoot: string, surface: KeySurface): ProjectKeyRead;
+export type PackageKeys = Map<string, Map<string, unknown>>;
+export type PackageKeyCompute = {
+    kind: 'ok';
+    keys: PackageKeys;
+} | {
+    kind: 'unavailable';
+    reason: string;
+};
+/**
+ * Generate the package side for `attachedTargets` by running the emitters
+ * against a scratch directory and capturing every key they record.
+ *
+ * Refuses (returns `unavailable`) when the package's template or tool manifest
+ * is missing: the emitters fail SOFT there (empty approval lists), and a
+ * soft-failed package side would read as "the package now approves nothing"
+ * and propose stripping the consumer's approvals.
+ */
+export declare function computePackageKeys(pkgRoot: string, attachedTargets: HarnessTarget[]): PackageKeyCompute;
+export type KeyClassification = 'new' | 'updated-safe' | 'conflict' | 'unchanged' | 'removed' | 'deleted-by-you' | 'untracked-new';
+export interface ClassifiedKey {
+    surface: KeySurface;
+    key: string;
+    classification: KeyClassification;
+    /** The package value (absent for `removed`). */
+    packageValue?: unknown;
+}
+export interface SurfaceKeyResult {
+    surface: KeySurface;
+    classified: ClassifiedKey[];
+    /** Keys under our prefix the manifest never recorded — HERS (namespace rule). */
+    yoursUnderPrefix: string[];
+    /** Manifest entry ids whose package key AND project key are both gone (dropped silently). */
+    dropEntries: string[];
+    /** Set when the project file exists but is not valid JSON — nothing is classified. */
+    invalid?: string;
+}
+/**
+ * Classify one surface. Only keys the package emits or the manifest recorded
+ * are ever classified; every other key in the file is the consumer's.
+ */
+export declare function classifySurfaceKeys(surface: KeySurface, packageKeys: Map<string, unknown>, project: ProjectKeyRead, manifestEntries: Record<string, ManifestEntry>): SurfaceKeyResult;
+/**
+ * Set `edits` (our keys only) into the surface file. Returns true iff the file
+ * was written. No write when every edit is already present with an equal parsed
+ * value. Insertion order is preserved (an existing key keeps its position; a new
+ * key is appended); 2-space indentation.
+ */
+export declare function writeSurfaceKeys(projectRoot: string, surface: KeySurface, edits: Array<{
+    key: string;
+    value: unknown;
+}>): boolean;
+//# sourceMappingURL=KeyGrain.d.ts.map