jg-plans 0.1.2 → 0.2.0

package/dist/files/mutations.js

@@ -1,13 +1,15 @@
-import { lstat, mkdir, open, rmdir, unlink } from 'node:fs/promises';
+import { lstat, mkdir, rmdir, unlink } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
 import { getErrorCode } from 'jg-exception';
-import { assertNoLinksBelow, readBoundedFile, writeFileAtomicIfUnchanged } from 'jg-fs';
+import { readBoundedFile } from 'jg-fs';
+import { hashValue } from 'jg-crypto';
 import { stringify } from 'yaml';
-import { z } from 'zod';
 import { parseMilestones, parsePlan } from "../documents/index.js";
-import { applyEdits, decodeSource, encodeSource, milestoneEdits, planEdits, } from "../edits/index.js";
+import { decodeSource, encodeSource, preparePlanUpdate } from "../edits/index.js";
 import { planErrors } from "../errors/index.js";
-import { CreatePlanOptionsSchema, DEFAULT_MAX_BYTES, PlanUpdateSchema, ReadOptionsSchema, } from "../protocol/index.js";
+import { CreatePlanOptionsSchema, PlanUpdateSchema, } from "../protocol/index.js";
+import { persistPrepared, readMutationSource, validateMutationOptions, writeExclusive, } from "./documents.js";
+import { withPlanDocumentLocks } from "./locks.js";
 const validateNewText = (value) => {
     if (typeof value === 'string')
         encodeSource(value);
@@ -20,19 +22,6 @@ const validateNewText = (value) => {
             validateNewText(item);
         }
 };
-const writeExclusive = async (root, path, bytes, owned) => {
-    await assertNoLinksBelow(root, path);
-    const handle = await open(path, 'wx');
-    try {
-        const stat = await handle.stat({ bigint: true });
-        owned.push({ path, dev: stat.dev, ino: stat.ino, bytes });
-        await handle.writeFile(bytes);
-        await handle.sync();
-    }
-    finally {
-        await handle.close();
-    }
-};
 /** Remove only files this call created and still recognizes, followed by the empty owned directory. */
 const cleanupCreation = async (directory, identity, owned) => {
     try {
@@ -81,6 +70,8 @@ const cleanupCreation = async (directory, identity, owned) => {
  * - JG_PLANS_INVALID_INPUT: Invalid jg-plans input
  * - JG_PLANS_UNSUPPORTED_ENCODING: Document text is not valid UTF-8
  * - JG_PLANS_DESTINATION_EXISTS: The plan destination already exists
+ * - JG_PLANS_LOCK_BUSY: The plan document is locked
+ * - JG_PLANS_LOCK_FAILED: The plan document lock operation failed
  * - JG_PLANS_WRITE_FAILED: The plan document could not be written
  */
 export const createPlan = async (options) => {
@@ -146,11 +137,17 @@ export const createPlan = async (options) => {
     }
     const owned = [];
     try {
-        await writeExclusive(root, join(directory, 'plan.md'), planBytes, owned);
-        if (milestoneBytes !== null)
-            await writeExclusive(root, join(directory, 'milestones.md'), milestoneBytes, owned);
+        await withPlanDocumentLocks(directory, milestoneBytes === null ? ['plan'] : ['plan', 'milestones'], async (selected) => {
+            await writeExclusive(selected, join(selected, 'plan.md'), planBytes, owned);
+            if (milestoneBytes !== null)
+                await writeExclusive(selected, join(selected, 'milestones.md'), milestoneBytes, owned);
+        });
     }
     catch (cause) {
+        // Release failure can follow a durable write. Preserve its files and uncertainty.
+        if (getErrorCode(cause) === 'JG_PLANS_LOCK_FAILED' ||
+            getErrorCode(cause) === 'JG_PLANS_LOCK_BUSY')
+            throw cause;
         const cleanupFailedPaths = await cleanupCreation(directory, identity, owned);
         throw planErrors.create('writeFailed', {
             cause,
@@ -161,15 +158,15 @@ export const createPlan = async (options) => {
     const milestones = input.milestones === undefined ? null : parseMilestones(input.milestones);
     return {
         directory,
-        plan,
-        milestones,
+        plan: { ...plan, sha256: hashValue(planBytes) },
+        milestones: milestones === null ? null : { ...milestones, sha256: hashValue(milestoneBytes) },
         diagnostics: [...plan.diagnostics, ...(milestones?.diagnostics ?? [])],
     };
 };
 /**
- * Apply one explicit metadata or marker patch, preserving every other source byte.
- * Callers serialize the whole read/edit/write operation. The final byte comparison
- * detects observed changes but has a comparison-to-rename race; no retry or lock is used.
+ * Apply an explicit narrow patch under the shared selected-document lock.
+ * Guard optional observed bytes before preparation; unchanged output is never replaced.
+ * Nonparticipating editors retain a final comparison-to-rename race.
  * @throws
  * - JG_PLANS_INVALID_INPUT: Invalid jg-plans input
  * - JG_PLANS_READ_FAILED: The selected document could not be read
@@ -177,66 +174,18 @@ export const createPlan = async (options) => {
  * - JG_PLANS_UNSAFE_EDIT: The requested edit is unsupported or ambiguous
  * - JG_PLANS_SOURCE_CHANGED: The document changed before replacement
  * - JG_PLANS_WRITE_FAILED: The plan document could not be written
+ * - JG_PLANS_LOCK_BUSY: The plan document is locked
+ * - JG_PLANS_LOCK_FAILED: The plan document lock operation failed
  */
 export const updatePlan = async (directory, patch, options = {}) => {
+    validateMutationOptions(directory, options);
     const validated = PlanUpdateSchema.safeParse(patch);
-    if (!validated.success ||
-        !z
-            .string()
-            .min(1)
-            .refine((value) => !value.includes('\0'))
-            .safeParse(directory).success ||
-        !ReadOptionsSchema.safeParse(options).success)
+    if (!validated.success)
         throw planErrors.create('invalidInput');
     const request = validated.data;
-    const selected = resolve(directory);
-    const path = join(selected, `${request.document}.md`);
-    let before;
-    try {
-        await assertNoLinksBelow(selected, path);
-        before = await readBoundedFile(path, options.maxBytes ?? DEFAULT_MAX_BYTES);
-    }
-    catch (cause) {
-        const reason = getErrorCode(cause);
-        throw planErrors.create('readFailed', { cause, ...(reason ? { data: { reason } } : {}) });
-    }
-    let source;
-    try {
-        source = decodeSource(before);
-    }
-    catch {
-        throw planErrors.create('unsupportedEncoding');
-    }
-    const edits = request.document === 'plan' ? planEdits(source, request) : milestoneEdits(source, request);
-    const after = applyEdits(before, source, edits);
-    const text = decodeSource(after);
-    const observation = request.document === 'plan' ? parsePlan(text) : parseMilestones(text);
-    if (request.document === 'plan') {
-        const updated = parsePlan(text);
-        if (updated.diagnostics.some((item) => item.code === 'INVALID_YAML' || item.code === 'UNTERMINATED_FRONTMATTER'))
-            throw planErrors.create('unsafeEdit', { data: { reason: 'invalid-serialized-frontmatter' } });
-        for (const [key, value] of Object.entries(request.set))
-            if (!Object.is(updated.metadata[key], value))
-                throw planErrors.create('unsafeEdit', {
-                    data: { reason: 'unsupported-serialized-value', field: key },
-                });
-    }
-    const changed = !before.equals(after);
-    if (changed) {
-        try {
-            await assertNoLinksBelow(selected, path);
-            await writeFileAtomicIfUnchanged(path, after, before);
-        }
-        catch (cause) {
-            if (getErrorCode(cause) === 'FILE_CHANGED')
-                throw planErrors.create('sourceChanged', { cause });
-            throw planErrors.create('writeFailed', { cause });
-        }
-    }
-    return {
-        directory: selected,
-        document: request.document,
-        changed,
-        diagnostics: observation.diagnostics,
-    };
+    return withPlanDocumentLocks(directory, [request.document], async (selected) => {
+        const before = await readMutationSource(selected, request.document, options, request.expectedSha256);
+        const prepared = preparePlanUpdate(decodeSource(before), request);
+        return persistPrepared(selected, request.document, before, prepared);
+    });
 };

package/dist/files/types.d.ts

@@ -1,9 +1,11 @@
-import type { IParsedMilestones, IParsedPlan } from '../documents/index.ts';
+import type { IParsedMilestones, IParsedPlan, IPlanFingerprint } from '../documents/index.ts';
+import type { IPreparedPlanEdit } from '../edits/index.ts';
 import type { IDiagnostic } from '../protocol/index.ts';
 /** Availability is independent per document; absence never implies approval or completion. */
 export type IDocumentRead<TDocument> = {
     state: 'readable';
     path: string;
+    sha256: string;
     value: TDocument;
 } | {
     state: 'missing';
@@ -17,19 +19,31 @@ export type IPlanInspection = {
     directory: string;
     plan: IDocumentRead<IParsedPlan>;
     milestones: IDocumentRead<IParsedMilestones>;
+    fingerprint?: IPlanFingerprint;
     diagnostics: IDiagnostic[];
 };
 /** Creation returns original generated/supplied sources and their useful observations. */
 export type IPlanCreation = {
     directory: string;
-    plan: IParsedPlan;
-    milestones: IParsedMilestones | null;
+    plan: IParsedPlan & {
+        sha256: string;
+    };
+    milestones: (IParsedMilestones & {
+        sha256: string;
+    }) | null;
     diagnostics: IDiagnostic[];
 };
 /** An update reports only its selected document; it does not inspect unrelated files. */
-export type IPlanUpdateResult = {
+export type IPlanUpdateResult = Omit<IPreparedPlanEdit, 'source'> & {
     directory: string;
     document: 'plan' | 'milestones';
-    changed: boolean;
+};
+/** Guarded source writes have the same digest/assignment result as narrow updates. */
+export type IPlanDocumentWriteResult = IPlanUpdateResult;
+export type IRemoveMilestonesResult = {
+    directory: string;
+    document: 'milestones';
+    changed: true;
+    sha256: null;
     diagnostics: IDiagnostic[];
 };

package/dist/files/utilities.d.ts

@@ -1,13 +1,13 @@
-import { type IReadOptions } from '../protocol/index.ts';
+import { type IInspectPlanOptions } from '../protocol/index.ts';
 import type { IPlanInspection } from './types.ts';
 /**
  * Read only plan.md and milestones.md beneath the explicitly selected directory.
  * Missing, oversized, unreadable, and undecodable files are observations; other
  * readable documents remain available. No history is discovered or restored.
- * @param directory Caller-selected path, including custom or legacy locations.
- * @param options Per-file byte bound, defaulting to 1 MiB.
+ * @param directory Caller-selected path, including custom locations.
+ * @param options Per-file byte bound, defaulting to 1 MiB, and optional fingerprint exclusions.
  * @returns Per-document availability, partial parsed data, and diagnostics.
  * @throws
  * - JG_PLANS_INVALID_INPUT: Invalid jg-plans input
  */
-export declare const inspectPlan: (directory: string, options?: IReadOptions) => Promise<IPlanInspection>;
+export declare const inspectPlan: (directory: string, options?: IInspectPlanOptions) => Promise<IPlanInspection>;

package/dist/files/utilities.js

@@ -1,11 +1,13 @@
 import { join, resolve } from 'node:path';
 import { getErrorCode } from 'jg-exception';
+import { hashValue } from 'jg-crypto';
 import { readBoundedFile } from 'jg-fs';
 import { z } from 'zod';
 import { parseMilestones, parsePlan } from "../documents/index.js";
+import { fingerprintObservation } from "../documents/fingerprints.js";
 import { decodeSource } from "../edits/index.js";
 import { planErrors } from "../errors/index.js";
-import { DEFAULT_MAX_BYTES, ReadOptionsSchema, } from "../protocol/index.js";
+import { DEFAULT_MAX_BYTES, InspectPlanOptionsSchema, } from "../protocol/index.js";
 const observeFile = async (directory, name, maxBytes, parse) => {
     const path = join(directory, `${name}.md`);
     let bytes;
@@ -49,28 +51,30 @@ const observeFile = async (directory, name, maxBytes, parse) => {
             ],
         };
     }
-    return { state: 'readable', path, value: parse(source) };
+    return { state: 'readable', path, sha256: hashValue(bytes), value: parse(source) };
 };
 /**
  * Read only plan.md and milestones.md beneath the explicitly selected directory.
  * Missing, oversized, unreadable, and undecodable files are observations; other
  * readable documents remain available. No history is discovered or restored.
- * @param directory Caller-selected path, including custom or legacy locations.
- * @param options Per-file byte bound, defaulting to 1 MiB.
+ * @param directory Caller-selected path, including custom locations.
+ * @param options Per-file byte bound, defaulting to 1 MiB, and optional fingerprint exclusions.
  * @returns Per-document availability, partial parsed data, and diagnostics.
  * @throws
  * - JG_PLANS_INVALID_INPUT: Invalid jg-plans input
  */
 export const inspectPlan = async (directory, options = {}) => {
+    const parsed = InspectPlanOptionsSchema.safeParse(options);
     if (!z
         .string()
         .min(1)
         .refine((value) => !value.includes('\0'))
         .safeParse(directory).success ||
-        !ReadOptionsSchema.safeParse(options).success)
+        !parsed.success)
         throw planErrors.create('invalidInput');
     const selected = resolve(directory);
-    const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+    const input = parsed.data;
+    const maxBytes = input.maxBytes ?? DEFAULT_MAX_BYTES;
     const [plan, milestones] = await Promise.all([
         observeFile(selected, 'plan', maxBytes, parsePlan),
         observeFile(selected, 'milestones', maxBytes, parseMilestones),
@@ -99,5 +103,18 @@ export const inspectPlan = async (directory, options = {}) => {
             severity: 'warning',
             message: 'Milestones remain without a plan; no plan is restored.',
         });
-    return { directory: selected, plan, milestones, diagnostics };
+    const fingerprint = input.fingerprint === undefined
+        ? undefined
+        : fingerprintObservation(plan.state === 'readable' ? plan.value : null, input.fingerprint);
+    if (fingerprint) {
+        const known = new Set(diagnostics);
+        diagnostics.push(...fingerprint.diagnostics.filter((item) => !known.has(item)));
+    }
+    return {
+        directory: selected,
+        plan,
+        milestones,
+        diagnostics,
+        ...(fingerprint ? { fingerprint } : {}),
+    };
 };

package/dist/index.d.ts

@@ -1,11 +1,13 @@
-export { checkPlan, parseMilestones, parsePlan } from './documents/index.ts';
-export type { ICheckResult, IFrontmatter, IMarker, IMilestone, IOverviewRow, IParsedMilestones, IParsedPlan, } from './documents/index.ts';
+export { checkPlan, parseMilestones, parsePlan, fingerprintPlan } from './documents/index.ts';
+export type { ICheckResult, IFrontmatter, IMarker, IMilestone, IOverviewRow, IParsedMilestones, IParsedPlan, ISourceSpan, IHeadingSection, IPlanFingerprint, } from './documents/index.ts';
 export { ERRORS } from './errors/index.ts';
 export { inspectPlan } from './files/index.ts';
-export { createPlan, updatePlan } from './files/index.ts';
+export { createPlan, updatePlan, writePlanDocument, removeMilestones, withPlanDocumentLocks, } from './files/index.ts';
+export { preparePlanUpdate, preparePlanDocumentWrite } from './edits/index.ts';
+export type { IPreparedPlanEdit, IAssignedMilestoneId } from './edits/index.ts';
 export type { IDocumentRead, IPlanInspection } from './files/index.ts';
-export type { IPlanCreation, IPlanUpdateResult } from './files/index.ts';
-export { PROTOCOL_VERSION, DiagnosticSchema, PlanDocumentsSchema, PlanMetadataSchema, ReadOptionsSchema, SourceLocationSchema, } from './protocol/index.ts';
-export type { IDiagnostic, IPlanDocuments, IPlanMetadata, IReadOptions, ISourceLocation, } from './protocol/index.ts';
-export { CreatePlanOptionsSchema, MilestoneSelectorSchema, MilestoneSetSchema, PlanSetSchema, PlanUpdateSchema, } from './protocol/index.ts';
-export type { ICreatePlanOptions, IPlanUpdate } from './protocol/index.ts';
+export type { IPlanCreation, IPlanUpdateResult, IPlanDocumentWriteResult, IRemoveMilestonesResult, } from './files/index.ts';
+export { PROTOCOL_VERSION, DiagnosticSchema, PlanDocumentsSchema, PlanMetadataSchema, ReadOptionsSchema, PlanFingerprintOptionsSchema, PlanFingerprintSchema, InspectPlanOptionsSchema, SourceLocationSchema, } from './protocol/index.ts';
+export type { IDiagnostic, IPlanDocuments, IPlanMetadata, IReadOptions, IPlanFingerprintOptions, IInspectPlanOptions, ISourceLocation, } from './protocol/index.ts';
+export { CreatePlanOptionsSchema, MilestoneSelectorSchema, MilestoneSetSchema, PlanSetSchema, PlanUpdateSchema, PlanDocumentWriteSchema, RemoveMilestonesSchema, } from './protocol/index.ts';
+export type { ICreatePlanOptions, IPlanUpdate, IPlanDocumentWrite, IRemoveMilestones, } from './protocol/index.ts';

package/dist/index.js

@@ -1,6 +1,7 @@
-export { checkPlan, parseMilestones, parsePlan } from "./documents/index.js";
+export { checkPlan, parseMilestones, parsePlan, fingerprintPlan } from "./documents/index.js";
 export { ERRORS } from "./errors/index.js";
 export { inspectPlan } from "./files/index.js";
-export { createPlan, updatePlan } from "./files/index.js";
-export { PROTOCOL_VERSION, DiagnosticSchema, PlanDocumentsSchema, PlanMetadataSchema, ReadOptionsSchema, SourceLocationSchema, } from "./protocol/index.js";
-export { CreatePlanOptionsSchema, MilestoneSelectorSchema, MilestoneSetSchema, PlanSetSchema, PlanUpdateSchema, } from "./protocol/index.js";
+export { createPlan, updatePlan, writePlanDocument, removeMilestones, withPlanDocumentLocks, } from "./files/index.js";
+export { preparePlanUpdate, preparePlanDocumentWrite } from "./edits/index.js";
+export { PROTOCOL_VERSION, DiagnosticSchema, PlanDocumentsSchema, PlanMetadataSchema, ReadOptionsSchema, PlanFingerprintOptionsSchema, PlanFingerprintSchema, InspectPlanOptionsSchema, SourceLocationSchema, } from "./protocol/index.js";
+export { CreatePlanOptionsSchema, MilestoneSelectorSchema, MilestoneSetSchema, PlanSetSchema, PlanUpdateSchema, PlanDocumentWriteSchema, RemoveMilestonesSchema, } from "./protocol/index.js";

package/dist/protocol/index.d.ts

@@ -1,5 +1,5 @@
 export { DEFAULT_MAX_BYTES, PROTOCOL_VERSION } from './constants.ts';
-export { DiagnosticSchema, PlanDocumentsSchema, PlanMetadataSchema, ReadOptionsSchema, SourceLocationSchema, } from './types.ts';
-export type { IDiagnostic, IPlanDocuments, IPlanMetadata, IReadOptions, ISourceLocation, } from './types.ts';
-export { CreatePlanOptionsSchema, MilestoneSelectorSchema, MilestoneSetSchema, PlanSetSchema, PlanUpdateSchema, } from './types.ts';
-export type { ICreatePlanOptions, IPlanUpdate } from './types.ts';
+export { DiagnosticSchema, PlanDocumentsSchema, PlanMetadataSchema, ReadOptionsSchema, PlanFingerprintOptionsSchema, PlanFingerprintSchema, InspectPlanOptionsSchema, SourceLocationSchema, } from './types.ts';
+export type { IDiagnostic, IPlanDocuments, IPlanMetadata, IReadOptions, IPlanFingerprintOptions, IPlanFingerprint, IInspectPlanOptions, ISourceLocation, } from './types.ts';
+export { CreatePlanOptionsSchema, MilestoneSelectorSchema, MilestoneSetSchema, PlanSetSchema, PlanUpdateSchema, PlanDocumentWriteSchema, RemoveMilestonesSchema, } from './types.ts';
+export type { ICreatePlanOptions, IPlanUpdate, IPlanDocumentWrite, IRemoveMilestones, } from './types.ts';

package/dist/protocol/index.js

@@ -1,3 +1,3 @@
 export { DEFAULT_MAX_BYTES, PROTOCOL_VERSION } from "./constants.js";
-export { DiagnosticSchema, PlanDocumentsSchema, PlanMetadataSchema, ReadOptionsSchema, SourceLocationSchema, } from "./types.js";
-export { CreatePlanOptionsSchema, MilestoneSelectorSchema, MilestoneSetSchema, PlanSetSchema, PlanUpdateSchema, } from "./types.js";
+export { DiagnosticSchema, PlanDocumentsSchema, PlanMetadataSchema, ReadOptionsSchema, PlanFingerprintOptionsSchema, PlanFingerprintSchema, InspectPlanOptionsSchema, SourceLocationSchema, } from "./types.js";
+export { CreatePlanOptionsSchema, MilestoneSelectorSchema, MilestoneSetSchema, PlanSetSchema, PlanUpdateSchema, PlanDocumentWriteSchema, RemoveMilestonesSchema, } from "./types.js";

package/dist/protocol/types.d.ts

@@ -45,6 +45,43 @@ export declare const ReadOptionsSchema: z.ZodObject<{
     maxBytes: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strict>;
 export type IReadOptions = z.infer<typeof ReadOptionsSchema>;
+/** Exclusions are caller policy; no metadata key is excluded implicitly. */
+export declare const PlanFingerprintOptionsSchema: z.ZodObject<{
+    excludeMetadataKeys: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type IPlanFingerprintOptions = z.infer<typeof PlanFingerprintOptionsSchema>;
+/** Closed JSON result for library and CLI consumers; unavailable identity has diagnostics. */
+export declare const PlanFingerprintSchema: z.ZodObject<{
+    sha256: z.ZodNullable<z.ZodString>;
+    excludeMetadataKeys: z.ZodArray<z.ZodString>;
+    diagnostics: z.ZodArray<z.ZodObject<{
+        code: z.ZodString;
+        severity: z.ZodEnum<{
+            error: "error";
+            info: "info";
+            warning: "warning";
+        }>;
+        document: z.ZodEnum<{
+            plan: "plan";
+            milestones: "milestones";
+        }>;
+        message: z.ZodString;
+        location: z.ZodOptional<z.ZodObject<{
+            offset: z.ZodNumber;
+            line: z.ZodNumber;
+            column: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strict>;
+export type IPlanFingerprint = z.infer<typeof PlanFingerprintSchema>;
+/** Request a structural fingerprint without another document read or parse. */
+export declare const InspectPlanOptionsSchema: z.ZodObject<{
+    maxBytes: z.ZodOptional<z.ZodNumber>;
+    fingerprint: z.ZodOptional<z.ZodObject<{
+        excludeMetadataKeys: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type IInspectPlanOptions = z.infer<typeof InspectPlanOptionsSchema>;
 /** Creation accepts JSON metadata, including project extensions and nonconforming known values. */
 export declare const CreatePlanOptionsSchema: z.ZodObject<{
     slug: z.ZodString;
@@ -82,8 +119,10 @@ export declare const PlanUpdateSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         revision: z.ZodExactOptional<z.ZodNumber>;
         status: z.ZodExactOptional<z.ZodString>;
     }, z.core.$strict>;
+    expectedSha256: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>, z.ZodObject<{
     document: z.ZodLiteral<"milestones">;
+    expectedSha256: z.ZodOptional<z.ZodString>;
     changes: z.ZodArray<z.ZodObject<{
         select: z.ZodXor<readonly [z.ZodObject<{
             id: z.ZodUUID;
@@ -97,3 +136,27 @@ export declare const PlanUpdateSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     }, z.core.$strict>>;
 }, z.core.$strict>], "document">;
 export type IPlanUpdate = z.infer<typeof PlanUpdateSchema>;
+/** Guarded document replacement; null expectations permit only absent milestone creation. */
+export declare const PlanDocumentWriteSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    document: z.ZodLiteral<"plan">;
+    expectedSha256: z.ZodString;
+    body: z.ZodString;
+    set: z.ZodOptional<z.ZodObject<{
+        id: z.ZodExactOptional<z.ZodString>;
+        created_at: z.ZodExactOptional<z.ZodISODateTime>;
+        updated_at: z.ZodExactOptional<z.ZodISODateTime>;
+        revision: z.ZodExactOptional<z.ZodNumber>;
+        status: z.ZodExactOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodObject<{
+    document: z.ZodLiteral<"milestones">;
+    expectedSha256: z.ZodNullable<z.ZodString>;
+    source: z.ZodString;
+    assignMissingIds: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>], "document">;
+export type IPlanDocumentWrite = z.infer<typeof PlanDocumentWriteSchema>;
+/** Removing a selected regular milestone document always requires its observed hash. */
+export declare const RemoveMilestonesSchema: z.ZodObject<{
+    expectedSha256: z.ZodString;
+}, z.core.$strict>;
+export type IRemoveMilestones = z.infer<typeof RemoveMilestonesSchema>;

package/dist/protocol/types.js

@@ -30,6 +30,25 @@ export const PlanDocumentsSchema = z.strictObject({
 export const ReadOptionsSchema = z.strictObject({
     maxBytes: z.number().int().positive().max(Number.MAX_SAFE_INTEGER).optional(),
 });
+/** Exclusions are caller policy; no metadata key is excluded implicitly. */
+export const PlanFingerprintOptionsSchema = z.strictObject({
+    excludeMetadataKeys: z.array(z.string()).optional(),
+});
+/** Closed JSON result for library and CLI consumers; unavailable identity has diagnostics. */
+export const PlanFingerprintSchema = z
+    .strictObject({
+    sha256: z
+        .string()
+        .regex(/^[a-f0-9]{64}$/)
+        .nullable(),
+    excludeMetadataKeys: z.array(z.string()).refine((keys) => new Set(keys).size === keys.length),
+    diagnostics: z.array(DiagnosticSchema),
+})
+    .refine((value) => value.sha256 !== null || value.diagnostics.length > 0);
+/** Request a structural fingerprint without another document read or parse. */
+export const InspectPlanOptionsSchema = ReadOptionsSchema.extend({
+    fingerprint: PlanFingerprintOptionsSchema.optional(),
+});
 /** Creation accepts JSON metadata, including project extensions and nonconforming known values. */
 export const CreatePlanOptionsSchema = z.strictObject({
     slug: z
@@ -68,11 +87,44 @@ export const MilestoneSetSchema = z
     .refine((value) => Object.keys(value).length > 0);
 /** A call edits one document with one closed patch, never arbitrary prose. */
 export const PlanUpdateSchema = z.discriminatedUnion('document', [
-    z.strictObject({ document: z.literal('plan'), set: PlanSetSchema }),
+    z.strictObject({
+        document: z.literal('plan'),
+        set: PlanSetSchema,
+        expectedSha256: z
+            .string()
+            .regex(/^[a-f0-9]{64}$/)
+            .optional(),
+    }),
     z.strictObject({
         document: z.literal('milestones'),
+        expectedSha256: z
+            .string()
+            .regex(/^[a-f0-9]{64}$/)
+            .optional(),
         changes: z
             .array(z.strictObject({ select: MilestoneSelectorSchema, set: MilestoneSetSchema }))
             .min(1),
     }),
 ]);
+/** Guarded document replacement; null expectations permit only absent milestone creation. */
+export const PlanDocumentWriteSchema = z.discriminatedUnion('document', [
+    z.strictObject({
+        document: z.literal('plan'),
+        expectedSha256: z.string().regex(/^[a-f0-9]{64}$/),
+        body: z.string(),
+        set: PlanSetSchema.optional(),
+    }),
+    z.strictObject({
+        document: z.literal('milestones'),
+        expectedSha256: z
+            .string()
+            .regex(/^[a-f0-9]{64}$/)
+            .nullable(),
+        source: z.string(),
+        assignMissingIds: z.boolean().optional(),
+    }),
+]);
+/** Removing a selected regular milestone document always requires its observed hash. */
+export const RemoveMilestonesSchema = z.strictObject({
+    expectedSha256: z.string().regex(/^[a-f0-9]{64}$/),
+});

package/docs/getting-started.md

@@ -17,7 +17,7 @@ node dist/cli/cli.js check --directory examples/with-milestones --json
 
 Inspect gives useful observations without requiring a conforming document. Check is optional. Missing files remain missing; neither operation restores history or approves execution. Document bodies are excluded from CLI output unless explicitly requested.
 
-The [API reference](../api/README.md) describes pure parsing, checking, selected-directory inspection, exclusive creation, and targeted metadata/marker updates. The [CLI guide](../cli/README.md) describes JSON input, automation envelopes, and exits. Read the [integration boundary](integrations.md) before building approval or execution behavior on these observations.
+The [API reference](../api/README.md) describes pure parsing, checking, selected-directory inspection, exclusive creation, pure preparation, guarded body/source writes, marker updates, removal, and shared locks. The [CLI guide](../cli/README.md) describes JSON input, automation envelopes, and exits. Read the [integration boundary](integrations.md) before building approval or execution behavior on these observations.
 
 ## Make an explicit edit
 
@@ -29,7 +29,7 @@ node dist/cli/cli.js create --slug small-change --input create.json --json
 
 Use the returned directory for inspection and updates. Update input such as `{ "document": "plan", "set": { "revision": 2, "status": "in progress" } }` changes only those requested fields. Supply updated_at explicitly when appropriate; nothing advances automatically. The [runnable example](../examples/library.mjs) shows the full library journey with cleanup limited to its own temporary directory.
 
-Serialize each document's complete read/edit/write operation. Unsupported YAML/ambiguous markers fail without writing, detected changes are not retried, and deleted targets are never recreated. The library preserves unrelated bytes; it does not rewrite prose or coordinate competing writers.
+Inspect exact hashes and supply expectedSha256 for guarded edits. Shared local document locks coordinate library, CLI, and participating consumers. Unsupported affected YAML/ambiguous markers fail without writing, detected changes are not retried, and existing-target expectations never recreate deleted files. Use explicit body/source writes when replacing prose; all unaffected bytes remain intact.
 
 ## Contributing
 

package/docs/integrations.md

@@ -1,49 +1,27 @@
-# Consumer integration
+# Consumer integrations
 
-Use [protocol 0.1](../protocol/0.1/README.md) as the compact shared format. A project can read Markdown itself or use the reference library/CLI. The [website](https://jg-plans.jesusgraterol.dev) identifies verified package availability. The protocol is usable without installing a tool or calling a website.
+Protocol 0.1 provides ordinary documents and deterministic operations. Consumers decide scope, authority, approval, progress semantics, retention, and reconciliation. A hash or checker result grants no permission.
 
-## Keep policy with the consumer
+## Skills: explicit runtime and freshness policy
 
-Unknown metadata and custom status strings belong to the document's author/project. Keep approvals, digests, authorization, scopes, priorities, allocations, registries, locks, execution and reconciliation in the consuming application. A closed local schema is a stricter consumer profile, not a universal protocol rule.
+Persisted planning workflows use the separately installed supported CLI, with explicit selected paths and structured JSON. Preflight the package version and envelope; never install it automatically. New skill plans use jg-plans/; an explicitly supplied custom path remains valid. Readers do not discover old roots or reconstruct deleted documents.
 
-For example, [the extension example](../examples/extensions/plan.md) contains project.owner and labels. A generic reader preserves them. The example's waiting-for-feedback status does not require every consumer to implement that workflow.
+Keep one identical compact **jg-plans protocol 0.1** section in the seven planning reader/writer skills. Role-specific rules stay outside it. jg-plan owns substantive revisions and explicit updated_at/revision changes; jg-breakdown owns semantic coverage and sequence binding; jg-execute owns authorized work and progress. Reviews/challenges remain read-only. No missing/custom status is coerced into permission or completion.
 
-## Roots and deletion
+Inspect before each mutation and supply the observed expectedSha256. Use write for plan-body/core-metadata changes or complete milestone source, update for narrow markers/core fields, and authorized guarded removal for an unnecessary sequence. Request missing UUIDs explicitly. Preserve existing identities and valid completion evidence; tools do not infer correspondence.
 
-Honor an explicit planning root. Otherwise preserve an established coding-agent-planning/ or custom root and use jg-plans/ for a new default. The reference CLI uses explicit paths; root discovery and publication exclusions belong to integrations. Do not move existing plans automatically.
+The skills bind a milestone sequence to plan id, revision, and structural content fingerprint, excluding exactly created_at, updated_at, revision, and status from that fingerprint. Other metadata and exact body remain covered. Revalidate coverage after revisions before stamping a fresh binding. A stale/unavailable binding cannot authorize sequence execution. Whole-plan execution without an expected sequence stays a supported single unit; disappearance of an expected sequence is a loss to report.
 
-Missing, edited, or deleted documents remain ordinary user choices. Return observations about what exists, preserve known progress, and avoid restoring removed files/history. An optional writer-format checker does not gate inspection or a safe independent edit. Status and metadata never grant execution permission.
+## HQ: one engine, application-owned authority
 
-## Editing and coordination
+Use public jg-plans observations/ranges, fingerprints, and pure preparation instead of another Markdown grammar. Retain HQ's strict project profile, host parser hook, approval digests, execution gates, limits, resource/error allocations, coordination journal, and reconciliation. Unknown contractual metadata and shared/trailing requirements must remain part of execution identity.
 
-Serialize the complete read/edit/write operation for each document, in one process and across processes. The standalone CLI does not coordinate concurrent writers. Atomic replacement and prior-content checks prevent partial output and detect observed conflicts, but retain a comparison-to-rename race.
+For journaled writes, prepare once and persist the exact resulting source, generated IDs, and timestamps before applying it. Acquire HQ metadata ownership before shared document locks. Inside withPlanDocumentLocks, use pure preparation and HQ persistence; do not nest filesystem mutation entry points. Release shared locks successfully before completing the HQ ledger. Release failures can follow durable writes and require reconciliation with admission closed.
 
-The reference implementation edits only explicitly requested core metadata or milestone markers, preserves unrelated bytes, and reports unsupported operations. It does not update overview tables or rewrite revision summaries. Missing selected documents are never recreated; inspection/checking does not gate a safe independent edit. Revision and timestamps change only when requested. Use the [API contracts](../api/README.md) and their closed schemas at a programmatic boundary; do not invent a second parser in a CLI wrapper.
+## Coordinating participating writers
 
-The selected directory and ancestors are trusted caller choices. The library rejects links below that root and preserves file permissions on replacement. Unsafe affected YAML/encoding/selector ambiguity leaves the source untouched. The caller must decide how to serialize the complete operation, including same-process calls. A writer that rewrites prose chooses its own best-effort snapshot location/retention; readers never depend on those snapshots.
+The CLI and every filesystem mutation share canonical local document lock names with the public callback. Locks cover one bounded read/prepare/persist operation, never model turns. Fixed order is plan then milestones; release is reverse. Dead owners remain busy until explicit operator inspection/recovery. The library never takes over automatically or removes an unfamiliar lock.
 
-## Adoption boundary
+File hashes guard exact bytes; structural fingerprints cover caller-selected content; approval digests are application policy. Preserve this distinction. There is no cross-document transaction and nonparticipating editors retain the documented comparison-to-replacement/deletion race. Partial outcomes must be reported honestly rather than rolled back over newer content.
 
-Adopting this protocol in jg-skills or an HQ project is separately scoped work. Protocol 0.1 stays provisional until jg-skills and at least one HQ consumer have exercised it. Those integrations are not prerequisites for using this project, and no downstream adoption is claimed here.
-
-## Skills: one shared section, distinct responsibilities
-
-Keep installed skills self-contained. Copy the compact writer/reader rules into one identically maintained section stamped **jg-plans protocol 0.1**. During the skills build, compare that section across every generated skill that includes it and fail on drift. Do not make loading or using a skill depend on the website, a network request, or running the jg-plans CLI.
-
-Keep role-specific instructions outside that common section:
-
-- **jg-plan:** write identity, creation/update timestamps, revision, and status; explain the intent and revision summary in Markdown. Revising a plan preserves existing milestones and progress unless the user asks to change or remove them. Avoid creating redundant companion files for a small task.
-- **jg-breakdown:** add optional milestones when they help. Place status immediately after the milestone heading; place an optional UUID ID on the next line. Preserve established identities and progress while revising the breakdown. Treat any overview as derived information.
-- **jg-execute:** read the selected documents and the user's actual authorization. Existing status markers describe progress; missing metadata, removed files, and checker findings do not create or revoke permission.
-- **jg-review and jg-review-session:** assess the relevant work against available evidence and the selected plan. Name missing evidence without inventing history or treating a deleted document as completion. The status line remains authoritative over an overview row.
-- **Publication/discovery skills:** recognize both coding-agent-planning/ and jg-plans/, as well as explicitly configured roots. Exclude planning files from broad publication unless the user deliberately includes them. Report a selected planning directory that is not ignored; do not silently change ignore rules or move documents.
-
-For root selection, honor an explicit path first. Otherwise keep the project's configured or established root, including an existing coding-agent-planning/ directory, before introducing jg-plans/ as a new default. When multiple roots are present, resolve the intended scope through the integration's configuration or the user's selection. A root name never grants permission to read unrelated old plans.
-
-Use the CLI only during development to validate documents produced by skill behavior evaluations. Include small plans, custom metadata/statuses, revisions with existing done milestones, edited marker placement, deleted metadata, and deleted companion files. Verify that skills preserve existing progress and obey their role, beyond checking preferred writer conformance. A development evaluation failure is feedback for the skill author; runtime document inspection and user edits remain available.
-
-## HQ consumers: depend on the reference implementation
-
-Use jg-plans for generic parsing and explicit document operations rather than maintaining another interpretation. Preserve a supported public consumer API with the smallest necessary wrapper, or make a documented breaking release when moving to the new dependency changes its contract. Test against that consumer's established documents and public API before migration.
-
-Keep approval digests, authorization, strict project frontmatter, resource schemas, execution, coordination, serialization, and reconciliation inside HQ. A stricter local profile may reject a document for a project-specific action; that does not make the document unreadable under the protocol. Avoid automatic repair, restoration of deleted plans, or silent rewriting to satisfy a closed project schema.
+See the [API](../api/README.md), [CLI](../cli/README.md), and [errors](../errors/README.md) for exact contracts. Protocol conformance is optional during inspection; stricter application admission remains consumer-owned.