jg-plans 0.1.0 → 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

@@ -1,6 +1,6 @@
 # Getting started
 
-**Development preview.** The protocol and examples are usable directly. The reference APIs and CLI are implemented; a public npm release has not been verified.
+The protocol and examples are usable directly. The reference library and CLI are optional; the [website's availability label](https://jg-plans.jesusgraterol.dev/docs/) identifies a verified published version. The checkout commands below work independently of npm publication.
 
 Start with an ordinary [small plan](../examples/small/plan.md). It contains five core metadata fields and a short Markdown body. Add [milestones](../examples/with-milestones/milestones.md) only when separate units help review the work. Users can edit, move, or delete these files.
 
@@ -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,8 +29,8 @@ 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
 
-The [development guide](https://github.com/jesusgraterol/jg-plans/blob/development/docs/development.md) owns checks and package/site boundaries. Tests exercise built root exports and an isolated installation of the actual tarball. The protocol remains provisional until separately approved skill and HQ integrations exercise it.
+The [development guide](https://github.com/jesusgraterol/jg-plans/blob/main/docs/development.md) owns checks and package/site boundaries. Tests exercise built root exports and an isolated installation of the actual tarball. The protocol remains provisional until separately approved skill and HQ integrations exercise it.

package/docs/integrations.md

@@ -1,27 +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 implemented reference library/CLI; public npm availability is not yet verified. 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. Existing progress and supported public consumer contracts need evidence before migration. Integration recipes and the final development-time conformance guidance are completed alongside the tested reference package and website; no downstream adoption is claimed here.
+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.