@semiont/make-meaning 0.5.31 → 0.5.33

package/dist/index.d.ts

@@ -230,10 +230,23 @@ interface KnowledgeBase {
 /** The lifecycle half of the working tree (GATEWAY.md D4a): the Archivist
  *  accessions, moves, removes and resolves — it never serves bytes. */
 type ContentLifecycle = Pick<WorkingTreeStore, 'register' | 'move' | 'remove' | 'resolveUri'>;
-/** The record's single write seam. `Stower` is the only appendEvent caller
- *  anywhere in make-meaning or the gateway (post-#1252): single-owner by
- *  construction. A second caller is a design smell, not a wiring chore. */
-type EventAppends = Pick<EventStore, 'appendEvent'>;
+/**
+ * The record's single write seam. `Stower` is the only appendEvent caller
+ * anywhere in make-meaning or the gateway (post-#1252): single-owner by
+ * construction. A second caller is a design smell, not a wiring chore.
+ *
+ * It carries a read — `viewStorage.get`, narrowed to `get` — because one write
+ * path is at-least-once and must not duplicate the log
+ * (COMMIT-ACK-FALSE-FAILURE F3): `mark:commit` diffs its batch against what the
+ * resource already holds. This does NOT reverse JOB-RESTART-SAFETY HD1, which
+ * rejected read-before-write for a WORKER reading a REMOTE store mid-recovery
+ * — "the thing it would read is exactly what is down". This read is inside the
+ * Archivist, against the store it is about to write, and cannot be down
+ * relative to itself.
+ */
+type EventAppends = Pick<EventStore, 'appendEvent'> & {
+    readonly viewStorage: Pick<ViewStorage, 'get'>;
+};
 /** Read-only reach into the event store: the log for queries, the
  *  materializer for on-demand view assembly (`assembleResourceGraph`). */
 interface EventStoreReads {
@@ -350,10 +363,22 @@ declare class Stower {
      *
      * Appends are sequential, not concurrent: the event log is the system of
      * record and a batch that half-lands under concurrency is harder to reason
-     * about than one that stops at the first failure. A partial batch is
-     * reported as a failure and the worker retries the WHOLE unit, which is safe
-     * because ids are deterministic (P3) and the annotation fold is idempotent
-     * by id — re-appending what already landed changes nothing.
+     * about than one that stops at the first failure.
+     *
+     * This channel is AT-LEAST-ONCE, and the log must not grow on a repeat
+     * (COMMIT-ACK-FALSE-FAILURE F3). Two paths re-send a batch that already
+     * landed: an acknowledgement lost after a successful append (the unit is
+     * never checkpointed, so the retry re-runs exactly the unit that landed), and
+     * a partial batch, reported as a failure and retried whole. Deterministic ids
+     * (JOB-RESTART-SAFETY P3) made those safe for the PROJECTIONS — the resource
+     * view and the graph both refuse a duplicate id — but a projection's guard
+     * says nothing about the log, which appends whatever it is handed. The result
+     * was a green graph over a doubled log: silent, and not undoable.
+     *
+     * So the batch is diffed against what the resource already holds. ONE view
+     * read per commit, never per annotation: the view for a 1,673-annotation
+     * resource is ~3 MB, and re-reading it per append would cost gigabytes of
+     * parsing for a single job.
      */
     private handleMarkCommit;
     private handleMarkDelete;

package/dist/index.js

@@ -11574,36 +11574,56 @@ var Stower = class {
    *
    * Appends are sequential, not concurrent: the event log is the system of
    * record and a batch that half-lands under concurrency is harder to reason
-   * about than one that stops at the first failure. A partial batch is
-   * reported as a failure and the worker retries the WHOLE unit, which is safe
-   * because ids are deterministic (P3) and the annotation fold is idempotent
-   * by id — re-appending what already landed changes nothing.
+   * about than one that stops at the first failure.
+   *
+   * This channel is AT-LEAST-ONCE, and the log must not grow on a repeat
+   * (COMMIT-ACK-FALSE-FAILURE F3). Two paths re-send a batch that already
+   * landed: an acknowledgement lost after a successful append (the unit is
+   * never checkpointed, so the retry re-runs exactly the unit that landed), and
+   * a partial batch, reported as a failure and retried whole. Deterministic ids
+   * (JOB-RESTART-SAFETY P3) made those safe for the PROJECTIONS — the resource
+   * view and the graph both refuse a duplicate id — but a projection's guard
+   * says nothing about the log, which appends whatever it is handed. The result
+   * was a green graph over a doubled log: silent, and not undoable.
+   *
+   * So the batch is diffed against what the resource already holds. ONE view
+   * read per commit, never per annotation: the view for a 1,673-annotation
+   * resource is ~3 MB, and re-reading it per append would cost gigabytes of
+   * parsing for a single job.
    */
   async handleMarkCommit(event) {
     if (!event._userId) {
       throw new Error("mark:commit missing _userId (gateway injection)");
     }
     const annotations = event.annotations ?? [];
+    const rid = resourceId(event.resourceId);
     try {
-      let persisted = 0;
+      const view = await this.stores.eventStore.viewStorage.get(rid);
+      const present = new Set((view?.annotations.annotations ?? []).map((a) => String(a.id)));
       for (const annotation of annotations) {
+        if (present.has(String(annotation.id))) continue;
         await this.stores.eventStore.appendEvent({
           type: "mark:added",
-          resourceId: resourceId(event.resourceId),
+          resourceId: rid,
           userId: userId(event._userId),
           version: 1,
           payload: { annotation }
         });
-        persisted++;
+        present.add(String(annotation.id));
       }
       this.logger.debug("Committed annotation batch", {
         correlationId: event.correlationId,
         resourceId: event.resourceId,
-        persisted
+        persisted: annotations.length
       });
       this.eventBus.get("mark:commit-ok").next({
         correlationId: event.correlationId,
-        response: { persisted, annotationIds: annotations.map((a) => String(a.id)) }
+        // The DURABLE count, which is what the acknowledgement means ("every
+        // annotation named by the command is in the event log"). Not an append
+        // tally: a retry whose annotations are all already present has
+        // succeeded, and must be indistinguishable from the first commit or the
+        // caller would have to interpret a 0 that means "all good".
+        response: { persisted: annotations.length, annotationIds: annotations.map((a) => String(a.id)) }
       });
     } catch (error) {
       this.logger.error("Failed to commit annotation batch", {
@@ -11829,7 +11849,11 @@ var Stower = class {
         jobId: event.jobId,
         jobType: event.jobType,
         ...event.annotationId ? { annotationId: event.annotationId } : {},
-        result: event.result
+        result: event.result,
+        // How durability was ESTABLISHED (COMMIT-ACK-FALSE-FAILURE). An
+        // acknowledged batch and one inferred from a probe are different
+        // claims; absent means the question never arose.
+        ...event.durability !== void 0 ? { durability: event.durability } : {}
       }
     });
   }
@@ -11846,7 +11870,19 @@ var Stower = class {
         jobId: event.jobId,
         jobType: event.jobType,
         ...event.annotationId ? { annotationId: event.annotationId } : {},
-        error: event.error
+        error: event.error,
+        // The worker's JUDGMENTS, not just its message. Both are computed where
+        // the error is still typed and are unrecoverable here — the only other
+        // witness in the log is `error`, a flattened English string. Spread
+        // conditionally: absent `failureClass` means UNRECOGNISED, a different
+        // claim from 'transient', and defaulting either would write a judgment
+        // nobody made into a log nobody can rewrite.
+        ...event.failureClass !== void 0 ? { failureClass: event.failureClass } : {},
+        ...event.willRetry !== void 0 ? { willRetry: event.willRetry } : {},
+        // How durability was ESTABLISHED (COMMIT-ACK-FALSE-FAILURE). An
+        // acknowledged batch and one inferred from a probe are different
+        // claims; absent means the question never arose.
+        ...event.durability !== void 0 ? { durability: event.durability } : {}
       }
     });
   }