pi-weave 0.1.12 → 0.1.13

package/src/web/shared/wire.ts

@@ -1,6 +1,6 @@
 /**
  * The wire contract between the loopback server and the browser client
- * (weave-workspace §5.3).
+ * (weave-workspace §5.3, §10).
  *
  * ## Why this file exists at all
  *
@@ -8,9 +8,9 @@
  * Node-flavoured TypeScript and a value import would drag `node:fs` into the
  * bundle. So everything both sides need is either a **type** here or a pure
  * function in `src/web/shared/`. This module is the type half — it is the
- * single place where the shape of an HTTP response or an SSE frame is
- * written down, and both the server that produces it and the client that
- * consumes it are typed from it.
+ * single place where the shape of an HTTP response is written down, and both
+ * the server that produces it and the client that consumes it are typed from
+ * it.
  *
  * ## Tier rules
  *
@@ -69,60 +69,6 @@ export type {
 } from "./graph";
 export { WIRE_EDGE_KINDS, WIRE_MODEL_OMITTED_KEYS, WIRE_NODE_KINDS } from "./graph";
 
-// --- liveness ----------------------------------------------------------------
-
-/**
- * Which half of the workspace an SSE frame is about.
- *
- * Deliberately coarser than the paths that produced it: macOS `fs.watch`
- * coalesces and can miss rapid bursts, so a frame means "something in this
- * scope changed, re-read it", never "here is the delta" (§6). A client that
- * treated frames as deltas would silently diverge the first time the OS
- * dropped one.
- */
-export type ChangeScope = "vault" | "repo" | "git";
-
-/** Every {@link ChangeScope}, for exhaustiveness checks and table tests. */
-export const CHANGE_SCOPES: readonly ChangeScope[] = ["vault", "repo", "git"];
-
-/**
- * One SSE frame.
- *
- * `stamp` is the graph's content digest at the moment the change was observed
- * — the same value `GET /api/graph` serves as its ETag (§5.3). It is the
- * dedupe key: a client that already holds this stamp has nothing to refetch,
- * which matters because the watcher's debounce window can still emit two
- * frames for one logical edit.
- *
- * Sharing one key with the ETag is load-bearing rather than tidy. While this
- * was `generatedAt`, an edit that did not advance the timestamp maximum
- * produced a frame the client deduped away against the stamp of the graph it
- * already held, so the refetch never happened (§15.6).
- */
-export interface ChangeEvent {
-  scope: ChangeScope;
-  stamp: string;
-}
-
-/** The `event:` name carried by every {@link ChangeEvent} frame. */
-export const CHANGE_EVENT_NAME = "change";
-
-/**
- * Structural guard for a decoded SSE `data:` payload.
- *
- * The client parses frames off a socket that survives server restarts and
- * proxy interference, so "it is JSON" is not the same as "it is ours".
- * Narrow rather than validate-and-throw: a malformed frame should cost a
- * skipped refetch, not an unhandled rejection inside `EventSource`'s
- * callback.
- */
-export function isChangeEvent(value: unknown): value is ChangeEvent {
-  if (typeof value !== "object" || value === null) return false;
-  const candidate = value as { scope?: unknown; stamp?: unknown };
-  if (typeof candidate.stamp !== "string") return false;
-  return CHANGE_SCOPES.includes(candidate.scope as ChangeScope);
-}
-
 // --- responses ---------------------------------------------------------------
 
 /**
@@ -166,15 +112,15 @@ export interface GraphPayload {
   dangling: Record<string, string[]>;
   /**
    * Server-precomputed layout, so the graph appears already laid out with no
-   * visible settling (§7.3). `null` when the server did not compute one —
+   * visible settling (§8). `null` when the server did not compute one —
    * which is the default, because the layout module imports `d3-force` and
    * the published package has zero runtime dependencies. The client then
    * runs the identical `src/web/shared/layout` code itself.
    */
   positions: Record<string, Point> | null;
   /**
-   * A **content digest** of this payload. The ETag body and the SSE dedupe
-   * key (§5.3, §6).
+   * A **content digest** of this payload. The ETag body and polling cache key
+   * (§15.6, §7.3).
    *
    * Opaque: a truncated SHA-256 of the serialized payload, and nothing may
    * parse it or derive meaning from its value. The only defined operation is
@@ -184,8 +130,8 @@ export interface GraphPayload {
    * This was `model.generatedAt` until §15.6. A max of input timestamps is
    * blind to any change that does not advance the maximum (a body edit, a
    * front-matter edit, deleting a note that is not the newest), so a
-   * conditional GET answered `304` with stale content and the SSE dedupe
-   * dropped the frame that would have corrected it.
+   * conditional GET answered `304` with stale content and the client cache
+   * kept the stale payload.
    *
    * For a human-readable "data as of" marker, read {@link GraphModel.generatedAt},
    * which still carries it — the status bar does exactly that.
@@ -193,134 +139,11 @@ export interface GraphPayload {
   stamp: string;
 }
 
-/**
- * `GET /api/note/:slug`, and the note half of every write response.
- *
- * The route used to serve a bare {@link ViewNote}. It carries a `revision`
- * as of P5 because the editor cannot save safely without one: a save that
- * does not say *which* state it was editing is a last-write-wins save, and
- * the two writers a vault actually has — `$EDITOR` and an agent's
- * `weave_note` call — are both fast enough to lose a paragraph to it.
- *
- * Carried in the **body** rather than as an `ETag`, deliberately. `api.ts`'s
- * {@link HttpResponse} port exposes `ok`, `status` and `json()` and nothing
- * else, because it exists so a two-line fake can stand in for `fetch` in a
- * repository with no DOM (§10). Reading a header would mean widening that
- * port for one field, and the field is a *property of the note*, not of the
- * HTTP representation — unlike `/api/graph`'s stamp, which really is a cache
- * validator and really does belong in an `ETag`.
- */
+/** `GET /api/note/:slug`. */
 export interface NotePayload {
   note: ViewNote;
-  /**
-   * Opaque version stamp for the file the note was read from.
-   *
-   * **Compare it, do not interpret it.** Core currently derives it from
-   * `mtimeMs:size` and says in the same breath that the shape is not part of
-   * the contract; a client that parsed a timestamp out of it would break the
-   * day core upgrades it to a digest. The only defined operation is equality
-   * against a later read of the same note.
-   */
-  revision: string;
 }
 
-/**
- * `POST /api/note/:slug` request body.
- *
- * Every field optional, and that is not laziness — it mirrors core's
- * `UpdateNoteInput`, where a metadata-only edit (retagging) and a body-only
- * edit (the textarea) are both first-class. A body of `{}` is a legal
- * request that bumps `updated` and nothing else.
- */
-export interface SaveNoteRequest {
-  /** Replacement Markdown body. Omit to change only metadata. */
-  body?: string;
-  /**
-   * Metadata to merge over the note's current values.
-   *
-   * `created` is absent by construction: it records when the note came into
-   * existence and an edit is not a re-creation. `updated` is absent because
-   * the server owns it — a client that could set it could make an edit look
-   * older than the state it overwrote.
-   */
-  meta?: {
-    title?: string;
-    tags?: string[];
-    source?: WireNoteSource;
-  };
-  /**
-   * The {@link NotePayload.revision} the client last read.
-   *
-   * Supply it and a stale save is refused with `409` and a
-   * {@link ConflictPayload} carrying the note as it now is. Omit it and the
-   * save is last-write-wins — which is a legitimate thing for the *user* to
-   * choose after seeing a conflict, and is exactly how "overwrite" is
-   * expressed: the same request, resent without this field.
-   */
-  expectedRevision?: string;
-}
-
-/** `POST /api/note/:slug/rename` request body. */
-export interface RenameNoteRequest {
-  /**
-   * The destination. Passed through core's `slugify`, so a human title is
-   * as acceptable as a slug and both land on the same file name.
-   */
-  slug: string;
-  title?: string;
-}
-
-/** `POST /api/note/:slug/move` request body. */
-export interface MoveNoteRequest {
-  /** Target folder path relative to notes/, or null/empty/"vault" for root. */
-  readonly targetFolder: string | null;
-}
-
-/** `POST /api/folder` request body. */
-export interface CreateFolderRequest {
-  readonly path: string;
-}
-
-/** `POST /api/folder` response. */
-export interface CreateFolderResult {
-  readonly ok: true;
-  readonly path: string;
-}
-
-/** `DELETE /api/note/:slug` response. Hard delete — there is no trash. */
-export interface DeleteNoteResult {
-  deleted: true;
-}
-
-/**
- * The `409` body for both write routes.
- *
- * A discriminated union rather than one shape with optional halves, because
- * the two cases carry genuinely different payloads and a client that has to
- * check `current !== undefined` before it can tell them apart is a client
- * that will one day forget to.
- *
- * The `conflict` arm carries the **whole current note**, not just its
- * revision. That is the difference between a UI that can offer
- * reload-or-overwrite immediately and one that has to issue a second request
- * before it can say anything useful — and the second request is one more
- * window in which the file moves again. Core hands the server this note as
- * part of the failure, so shipping it costs nothing.
- */
-export type ConflictPayload =
-  | {
-      error: string;
-      reason: "conflict";
-      /** The note as it is on disk right now, with its current revision. */
-      current: NotePayload;
-    }
-  | {
-      error: string;
-      reason: "collision";
-      /** The destination slug that is already taken. */
-      slug: string;
-    };
-
 /** `GET /api/okf/:rel`. */
 export interface OkfFilePayload {
   /** The requested path, relative to `<cwd>/.okf`. Echoed, never resolved. */
@@ -364,13 +187,4 @@ export const BOOTSTRAP_ELEMENT_ID = "weave-bootstrap";
 export interface Bootstrap {
   /** Absolute path the workspace was started in. */
   cwd: string;
-  /** Absolute path of the vault root. */
-  vaultRoot: string;
-  /**
-   * Random per-boot id. `EventSource` reconnects transparently across a
-   * server restart, so without this a client cannot distinguish two cases it
-   * must handle differently: "I missed some frames" (refetch) and "this is a
-   * different server" (full reload).
-   */
-  session: string;
 }