@oh-my-pi/hashline 15.5.15 → 15.6.0

package/dist/types/messages.d.ts

@@ -44,3 +44,18 @@ export declare const RECOVERY_SESSION_CHAIN_WARNING = "Recovered from a stale fi
  * model verifies before continuing.
  */
 export declare const RECOVERY_SESSION_REPLAY_WARNING = "Recovered by replaying your edits onto the current file content \u2014 your previous edit in this session changed line(s) you re-targeted with a stale hash. Verify the diff matches your intent before continuing.";
+/**
+ * Warning emitted when an `insert head:` / `insert tail:` edit is applied to an
+ * existing file whose snapshot tag is stale (the file drifted since the read).
+ * Head/tail insert position is content-independent — "start"/"end" cannot move
+ * with drift — so this is non-fatal: the edit applies onto the live content and
+ * we surface the drift instead of hard-failing (unlike an anchored mismatch).
+ */
+export declare const HEADTAIL_DRIFT_WARNING = "Applied an `insert head:`/`insert tail:` edit onto the current file content even though the snapshot tag was stale (the file changed since your read). Head/tail position is content-independent, so the insert was not rejected \u2014 but re-read if the drift was unexpected.";
+/**
+ * Error text emitted when a hashline section omits the mandatory snapshot tag.
+ * The tag is REQUIRED on every section, enforced identically by the apply path
+ * ({@link Patcher.prepare}) and the preview/diff path, so both surfaces reuse
+ * this single builder to stay in lockstep.
+ */
+export declare function missingSnapshotTagMessage(sectionPath: string): string;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/hashline",
-	"version": "15.5.15",
+	"version": "15.6.0",
 	"description": "Hashline: a compact, line-anchored patch language and applier. Pluggable FS/IO so it works over disk, in-memory, or any custom backend.",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -34,7 +34,7 @@
 	},
 	"dependencies": {
 		"diff": "^9.0.0",
-		"lru-cache": "11.3.6"
+		"lru-cache": "11.5.1"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"

package/src/grammar.lark

@@ -3,7 +3,7 @@ begin_patch: "*** Begin Patch" LF
 end_patch:   "*** End Patch" LF?
 
 file_patch: file_header hunk+
-file_header: "¶" filename ("#" file_hash)? LF
+file_header: "¶" filename "#" file_hash LF
 file_hash: /[0-9A-F]{4}/
 filename: /[^\s#]+/
 

package/src/messages.ts

@@ -5,6 +5,8 @@
  * them.
  */
 
+import { HL_FILE_HASH_SEP, HL_FILE_PREFIX } from "./format";
+
 /** Lines of context shown either side of a hash mismatch. */
 export const MISMATCH_CONTEXT = 2;
 
@@ -65,3 +67,23 @@ export const RECOVERY_SESSION_CHAIN_WARNING =
  */
 export const RECOVERY_SESSION_REPLAY_WARNING =
 	"Recovered by replaying your edits onto the current file content — your previous edit in this session changed line(s) you re-targeted with a stale hash. Verify the diff matches your intent before continuing.";
+
+/**
+ * Warning emitted when an `insert head:` / `insert tail:` edit is applied to an
+ * existing file whose snapshot tag is stale (the file drifted since the read).
+ * Head/tail insert position is content-independent — "start"/"end" cannot move
+ * with drift — so this is non-fatal: the edit applies onto the live content and
+ * we surface the drift instead of hard-failing (unlike an anchored mismatch).
+ */
+export const HEADTAIL_DRIFT_WARNING =
+	"Applied an `insert head:`/`insert tail:` edit onto the current file content even though the snapshot tag was stale (the file changed since your read). Head/tail position is content-independent, so the insert was not rejected — but re-read if the drift was unexpected.";
+
+/**
+ * Error text emitted when a hashline section omits the mandatory snapshot tag.
+ * The tag is REQUIRED on every section, enforced identically by the apply path
+ * ({@link Patcher.prepare}) and the preview/diff path, so both surfaces reuse
+ * this single builder to stay in lockstep.
+ */
+export function missingSnapshotTagMessage(sectionPath: string): string {
+	return `Missing hashline snapshot tag for edit to ${sectionPath}; use \`${HL_FILE_PREFIX}${sectionPath}${HL_FILE_HASH_SEP}tag\` from your latest read/search output. To create a new file, use the write tool.`;
+}

package/src/patcher.ts

@@ -23,10 +23,11 @@
  * filesystem configuration.
  */
 import { applyEdits } from "./apply";
-import { computeFileHash, formatHashlineHeader, HL_FILE_HASH_SEP, HL_FILE_PREFIX } from "./format";
+import { computeFileHash, formatHashlineHeader } from "./format";
 import type { Filesystem, WriteResult } from "./fs";
 import { isNotFound } from "./fs";
 import type { Patch, PatchSection } from "./input";
+import { HEADTAIL_DRIFT_WARNING, missingSnapshotTagMessage } from "./messages";
 import { MismatchError } from "./mismatch";
 import { detectLineEnding, type LineEnding, normalizeToLF, restoreLineEndings, stripBom } from "./normalize";
 import { Recovery, type RecoveryResult } from "./recovery";
@@ -102,11 +103,9 @@ function hasAnchorScopedEdit(edits: readonly Edit[]): boolean {
 	});
 }
 
-function assertSectionHashAllowed(sectionPath: string, fileHash: string | undefined, edits: readonly Edit[]): void {
-	if (fileHash !== undefined || !hasAnchorScopedEdit(edits)) return;
-	throw new Error(
-		`Missing hashline snapshot tag for anchored edit to ${sectionPath}; use \`${HL_FILE_PREFIX}${sectionPath}${HL_FILE_HASH_SEP}tag\` from your latest read/search output.`,
-	);
+function assertSectionHashPresent(sectionPath: string, fileHash: string | undefined): void {
+	if (fileHash !== undefined) return;
+	throw new Error(missingSnapshotTagMessage(sectionPath));
 }
 
 function recoveryToApplyResult(result: RecoveryResult): ApplyResult {
@@ -213,13 +212,13 @@ export class Patcher {
 	 */
 	async prepare(section: PatchSection): Promise<PreparedSection> {
 		const { edits, warnings: parseWarnings } = section.parse();
-		assertSectionHashAllowed(section.path, section.fileHash, edits);
+		assertSectionHashPresent(section.path, section.fileHash);
 
 		const canonicalPath = this.fs.canonicalPath(section.path);
 		await this.fs.preflightWrite(section.path);
 		const { exists, rawContent } = await this.#tryRead(section.path);
-		if (!exists && hasAnchorScopedEdit(edits)) {
-			throw new Error(`File not found: ${section.path}`);
+		if (!exists) {
+			throw new Error(`File not found: ${section.path}. Use the write tool to create new files.`);
 		}
 
 		const { bom, text } = stripBom(rawContent);
@@ -320,6 +319,14 @@ export class Patcher {
 		// Whole-file unchanged → the tag still names the live content, so an
 		// edit anchored at ANY line (displayed or not) is safe to apply.
 		if (computeFileHash(normalized) === expected) return applyEdits(normalized, [...edits]);
+		// Head/tail-only inserts are position-stable: "start"/"end" cannot move
+		// with content drift, so a stale tag is non-fatal. Apply onto the live
+		// content and warn instead of hard-failing — unlike an anchored
+		// mismatch, which cannot be safely relocated and must reject.
+		if (!hasAnchorScopedEdit(edits)) {
+			const result = applyEdits(normalized, [...edits]);
+			return { ...result, warnings: [HEADTAIL_DRIFT_WARNING, ...(result.warnings ?? [])] };
+		}
 		// File drifted: try to replay the edit against the version the tag
 		// names and 3-way-merge it onto the live content.
 		const recovered = this.recovery.tryRecover({

package/src/prompt.md

@@ -1,7 +1,7 @@
 Your patch language names lines to replace, delete, or insert at, then lists the new content. Rule of thumb: a header ending in `:` is followed by `+` body rows; `delete` has no body.
 
 <headers>
-Every file section starts with `¶PATH#TAG`. `TAG` is the 3-char snapshot tag from your latest `read`/`search`. REQUIRED for any hunk that names line numbers. Hashless `¶PATH` is allowed only for new-file creation or a patch that is purely `insert head:` / `insert tail:`.
+Every file section starts with `¶PATH#TAG`. `TAG` is the 4-hex snapshot tag from your latest `read`/`search`, and is REQUIRED on every section — there is no hashless form. To create a new file, use the `write` tool; hashline only edits files that already exist.
 </headers>
 
 <ops>
@@ -23,6 +23,9 @@ There is NO other body row kind. NEVER write `-old` or a bare/context line. To k
 <rules>
 - Line numbers come from `read`/`search` (`LINE:TEXT`). Copy the `¶PATH#TAG` header; use the bare LINE numbers.
 - Numbers refer to the ORIGINAL file and stay valid for the whole patch — they do not shift as hunks apply.
+- Across calls they do NOT survive: each applied edit mints a fresh `#TAG` and renumbers the file, so the tag and line numbers you just used are dead. Anchor the next edit on the `¶PATH#TAG` and lines from the edit response (or re-`read`), never on pre-edit numbers.
+- A line number is an offset, not a structural boundary: never `insert after N` into a construct you have not read, and never start or end a `replace`/`delete` range mid-expression or mid-block. If unsure what is on those lines, `read` them first.
+- On a stale-tag rejection — or any result you cannot fully account for — STOP and re-`read`. Never stack more line-numbered edits onto output you have not re-grounded; that compounds corruption.
 - One hunk per range; the body is the final content, never an old/new pair.
 - To change lines 2 and 5 while keeping 3–4, issue two hunks (`replace 2..2:` and `replace 5..5:`). Untouched lines are simply absent from every range.
 </rules>
@@ -30,7 +33,7 @@ There is NO other body row kind. NEVER write `-old` or a bare/context line. To k
 <example>
 Original (the exact shape `read` returns):
 ```
-¶greet.py#A1
+¶greet.py#A1B2
 1:def greet(name):
 2:    msg = "Hello, " + name
 3:    print(msg)
@@ -39,14 +42,14 @@ Original (the exact shape `read` returns):
 
 Insert a guard after line 1:
 ```
-¶greet.py#A1
+¶greet.py#A1B2
 insert after 1:
 +    if not name: name = "stranger"
 ```
 
 Replace line 2 with two lines:
 ```
-¶greet.py#A1
+¶greet.py#A1B2
 replace 2..2:
 +    greeting = "Hi"
 +    msg = f"{greeting}, {name}"
@@ -54,13 +57,13 @@ replace 2..2:
 
 Delete line 3:
 ```
-¶greet.py#A1
+¶greet.py#A1B2
 delete 3
 ```
 
 Add a header and trailer:
 ```
-¶greet.py#A1
+¶greet.py#A1B2
 insert head:
 +# generated header
 insert tail: