jg-plans 0.1.0 → 0.2.0

package/errors/README.md

@@ -10,17 +10,19 @@ Document-format diagnostics are observations. They are separate from the operati
 | UNSAFE_EDIT          | JG_PLANS_UNSAFE_EDIT          | The requested edit is unsupported or ambiguous | Unsupported affected YAML/marker structure, selector ambiguity, or invalid spans; nothing is written. |
 | DESTINATION_EXISTS   | JG_PLANS_DESTINATION_EXISTS   | The plan destination already exists            | Exclusive creation refuses an existing path.                                                          |
 | SOURCE_CHANGED       | JG_PLANS_SOURCE_CHANGED       | The document changed before replacement        | A prior-content comparison observed different bytes; no retry occurs.                                 |
-| WRITE_FAILED         | JG_PLANS_WRITE_FAILED         | The plan document could not be written         | Creation or replacement failed; inspect any cleanupFailedPaths.                                       |
+| WRITE_FAILED         | JG_PLANS_WRITE_FAILED         | The plan document could not be written         | Creation, replacement, or removal failed; inspect any cleanupFailedPaths.                             |
+| LOCK_BUSY            | JG_PLANS_LOCK_BUSY            | The plan document is locked                    | Immediate participating-writer contention, including dead owners; no automatic recovery.              |
+| LOCK_FAILED          | JG_PLANS_LOCK_FAILED          | The plan document lock operation failed        | Canonicalization/acquisition/release failed; release can follow durable writes.                       |
 
-parsePlan, parseMilestones, checkPlan, and inspectPlan can throw INVALID_INPUT for incompatible operation arguments. Inspection returns file failures as diagnostics rather than throwing away another readable document. createPlan can throw INVALID_INPUT, UNSUPPORTED_ENCODING, DESTINATION_EXISTS, and WRITE_FAILED. updatePlan can throw INVALID_INPUT, READ_FAILED, UNSUPPORTED_ENCODING, UNSAFE_EDIT, SOURCE_CHANGED, and WRITE_FAILED. Mutation failures exit 2 in the CLI.
+parsePlan, parseMilestones, checkPlan, and inspectPlan can throw INVALID_INPUT for incompatible operation arguments. Inspection returns file failures as diagnostics rather than throwing away another readable document. Pure preparation can throw INVALID_INPUT, UNSUPPORTED_ENCODING, UNSAFE_EDIT, and SOURCE_CHANGED. createPlan adds DESTINATION_EXISTS/WRITE_FAILED and lock errors. updatePlan/writePlanDocument add READ_FAILED/WRITE_FAILED and lock errors. removeMilestones uses INVALID_INPUT, READ_FAILED, UNSUPPORTED_ENCODING, SOURCE_CHANGED, WRITE_FAILED, and lock errors. withPlanDocumentLocks validates arguments and reports lock failures while propagating callback errors after successful release. Mutation failures exit 2 in the CLI.
 
 Stable messages exclude user text. Internal causes may retain detailed provider errors and are never emitted by the CLI. Public error.data may contain a safe provider/unsupported-edit reason, an affected core field, or cleanupFailedPaths. For example, unsupported-metadata-value means an affected scalar uses an unsupported form, and noncanonical-id-insertion means a new ID cannot be inserted after a canonical status marker. Reason details refine the stable operational code; they do not quote source. Failed JSON parsing also omits the unsafe syntax-error cause.
 
-Failed creation cleans only still-recognizable owned partial files and its empty plan directory. If user edits or I/O failures prevent that cleanup, paths are reported without deleting intervening content. The selected storage root can remain empty. Updates never recreate missing documents, rewrite bodies, or recover history. The [API](../api/README.md) documents conservative YAML forms and caller coordination requirements.
+Failed creation cleans only still-recognizable owned partial files and its empty plan directory. If user edits or I/O failures prevent that cleanup, paths are reported without deleting intervening content. The selected storage root can remain empty. Existing-target guards never recreate deleted documents. Explicit write operations can replace the selected body/source; they do not recover history. The [API](../api/README.md) documents conservative YAML forms and shared local locks. Acquisition failures report mutationOutcome not-applied. Release failures report operationCompleted and mutationOutcome uncertain if the callback started; inspect durable state before retrying. Internal AggregateError causes retain callback/release failures. Locks are not automatically recovered.
 
 ## Document diagnostics
 
-- Plan structure: MISSING_FRONTMATTER, UNTERMINATED_FRONTMATTER, INVALID_YAML, YAML_WARNING, YAML_VALUE_UNAVAILABLE, METADATA_NOT_MAPPING, MISSING_METADATA_FIELD, INVALID_METADATA_FIELD.
+- Plan structure: MISSING_FRONTMATTER, UNTERMINATED_FRONTMATTER, INVALID_YAML, YAML_WARNING, YAML_VALUE_UNAVAILABLE, METADATA_NOT_MAPPING, MISSING_METADATA_FIELD, INVALID_METADATA_FIELD, FINGERPRINT_UNAVAILABLE.
 - Availability: MISSING_PLAN, MISSING_MILESTONES, ORPHAN_MILESTONES, UNREADABLE_DOCUMENT, FILE_TOO_LARGE, INVALID_ENCODING.
 - Milestones: NO_MILESTONES, INVALID_ORDINAL, NONSEQUENTIAL_ORDINAL, DUPLICATE_ORDINAL, EMPTY_MILESTONE_TITLE, MISSING_STATUS, EMPTY_STATUS, DUPLICATE_STATUS, MISPLACED_STATUS, DUPLICATE_ID_MARKER, INVALID_MILESTONE_ID, DUPLICATE_ID, MISPLACED_ID, AMBIGUOUS_OVERVIEW, OVERVIEW_MISMATCH.
 

package/examples/library.mjs

@@ -1,7 +1,15 @@
 import { mkdtemp, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { checkPlan, createPlan, inspectPlan, updatePlan } from 'jg-plans';
+import {
+  checkPlan,
+  createPlan,
+  inspectPlan,
+  updatePlan,
+  writePlanDocument,
+  removeMilestones,
+  preparePlanDocumentWrite,
+} from 'jg-plans';
 
 // This example owns a temporary root. Never recursively remove a user's planning root.
 const root = await mkdtemp(join(tmpdir(), 'jg-plans-example-'));
@@ -12,18 +20,42 @@ try {
     body: '# A small change\n\nKeep the intent close to the work.\n',
     milestones: '## Milestone 1: Implement\n**Status:** pending\n',
   });
-  // Await the complete operation before starting the next edit of this document.
+  // A consumer journal stores exact prepared source/IDs once, then replays those bytes.
+  const prepared = preparePlanDocumentWrite(created.milestones.source, {
+    document: 'milestones',
+    expectedSha256: created.milestones.sha256,
+    source: created.milestones.source,
+    assignMissingIds: true,
+  });
+  const written = await writePlanDocument(created.directory, {
+    document: 'milestones',
+    expectedSha256: created.milestones.sha256,
+    source: prepared.source,
+  });
   await updatePlan(created.directory, {
     document: 'milestones',
+    expectedSha256: written.sha256,
     changes: [{ select: { ordinal: 1 }, set: { status: 'done' } }],
   });
   const observed = await inspectPlan(created.directory);
+  // Body/core metadata can also be replaced together using the observed digest.
+  if (observed.plan.state === 'readable')
+    await writePlanDocument(created.directory, {
+      document: 'plan',
+      expectedSha256: observed.plan.sha256,
+      body: observed.plan.value.body,
+      set: { revision: 2 },
+    });
   const result = checkPlan({
     ...(observed.plan.state === 'readable' ? { plan: observed.plan.value.source } : {}),
     ...(observed.milestones.state === 'readable'
       ? { milestones: observed.milestones.value.source }
       : {}),
   });
+  if (observed.milestones.state === 'readable')
+    await removeMilestones(created.directory, {
+      expectedSha256: observed.milestones.sha256,
+    });
   console.log(JSON.stringify({ conforms: result.conforms, diagnostics: result.diagnostics }));
 } finally {
   await rm(root, { recursive: true, force: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jg-plans",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A compact planning protocol for people and coding agents.",
   "type": "module",
   "sideEffects": false,
@@ -49,7 +49,6 @@
     "@eslint/js": "10.0.1",
     "@types/node": "24.10.1",
     "eslint": "10.12.0",
-    "jg-crypto": "0.3.0",
     "jg-fetch": "0.5.0",
     "prettier": "3.8.3",
     "prettier-plugin-astro": "1.1.1",
@@ -71,9 +70,11 @@
     "tailwindStylesheet": "./website/src/styles/global.css"
   },
   "dependencies": {
+    "jg-crypto": "0.3.0",
     "jg-exception": "1.7.0",
-    "jg-fs": "1.6.0",
+    "jg-fs": "1.7.0",
     "jg-process": "1.6.1",
+    "jg-utilities": "1.7.0",
     "yaml": "2.9.1",
     "zod": "4.6.7"
   },

package/protocol/0.1/README.md

@@ -89,6 +89,12 @@ An optional Overview table with Milestone, Name, and Status columns is derived f
 
 Caller-supplied milestone source remains verbatim. A caller generating that source follows writer rules; nonconforming supplied source receives diagnostics rather than automatic normalization. Updating a recognizable misplaced marker may preserve its location with a diagnostic; it does not claim to have repaired conformance.
 
+## Source observations
+
+Optional milestone frontmatter is a project-owned mapping; it does not require the plan's five preferred fields. Readers preserve it and exclude it from Markdown heading/marker scanning. Both document kinds retain complete original source, including BOM and line endings. The reference library exposes preamble and heading/body ranges, milestone heading ends, and recognized Overview table ranges so consumers can retain requirements outside numbered milestone bodies.
+
+Exact-byte document hashes and optional structural fingerprints are library observations, not protocol approval fields. Structural fingerprints cover exact body text and raw metadata after explicitly requested top-level exclusions; the generic default excludes nothing. Unavailable structure is reported without discarding useful text or inferring authority. Consumer profiles choose their own policy.
+
 ## Revisions, history, and deletion
 
 For substantive agent revisions, recommend a short inline summary explaining actual scope changes and preserving known progress. Do not silently reset completed work to pending.
@@ -101,13 +107,13 @@ Inspection explicitly distinguishes a missing plan, missing milestone file, orph
 
 ## Reference mutation boundary
 
-The first reference library supports creation and targeted edits to core metadata and milestone status/ID markers. It does not rewrite general Markdown, normalize extension fields, reorder milestones, remap progress, maintain a snapshot service, or migrate repositories.
+The reference library supports creation, narrow core-metadata/marker patches, guarded plan-body/core-metadata replacement, complete milestone-source replacement with explicit missing-ID assignment, and guarded milestone removal. Pure preparation supplies exact output for consumer persistence. It never remaps progress, normalizes unrelated extension fields, maintains a snapshot service, or migrates repositories.
 
 For existing documents, preserve the original bytes outside the exact requested values or inserted field/marker lines, including unknown data, comments, whitespace, BOM, Unicode, CRLF, and final-newline state. Decode UTF-8 strictly and map character positions to original byte spans correctly. Unsupported or ambiguous affected YAML, unsupported encoding, invalid UTF-8, or unencodable replacement text leaves that file unchanged with a specific failure.
 
 A malformed plan must not prevent independent milestone observations or an unambiguous marker edit. Update does not recreate a missing/deleted target. Creation never overwrites an existing destination.
 
-Consumers serialize the whole read/edit/write operation for each document, including concurrent calls in one process and across processes. The standalone CLI provides no cross-process coordination: run its updates to the same document sequentially. Atomic replacement prevents partial-file output; a prior-content check detects observed changes but has a comparison-to-rename race. Do not claim protection against every writer or silently retry over newer contents.
+Library and CLI filesystem mutations share short local document locks, acquired in plan-then-milestones order and released in reverse. The public lock callback allows consumers to prepare and persist under that same namespace. Busy/dead owners fail immediately; recovery is an explicit operator decision. Atomic replacement and byte guards detect observed changes, but nonparticipating editors retain a comparison-to-replacement/deletion race. No cross-document transaction, automatic retry, or completion inference is supplied. See the [API](../../api/README.md#shared-document-locks) for lock names and uncertain release outcomes.
 
 ## Consumer-owned policy