pi-weave 0.1.11 → 0.1.13

package/src/web/client/api.ts

@@ -3,8 +3,8 @@
  *
  * One function per route, each returning a discriminated {@link ApiResult}
  * rather than throwing. That is the whole design decision here, and it is
- * driven by §6: the client refetches on every SSE frame and on every
- * reconnect, so a failed request is a *normal, frequent* occurrence — the
+ * driven by §6: the client refetches on every poll and on every explicit
+ * refresh, so a failed request is a *normal, frequent* occurrence — the
  * server may be mid-restart, the session may have been killed, the token may
  * have rotated. Exceptions are for the unexpected, and none of these are.
  * A caller that must handle "the server went away" on every call is better
@@ -36,17 +36,7 @@
  * fortnight.
  */
 
-import type {
-  ConflictPayload,
-  DeleteNoteResult,
-  GraphPayload,
-  NotePayload,
-  OkfFilePayload,
-  OpenResult,
-  SaveNoteRequest,
-  SearchPayload,
-  ViewNote,
-} from "../shared/wire";
+import type { GraphPayload, NotePayload, OpenResult, SearchPayload, ViewNote } from "../shared/wire";
 
 // --- the injected HTTP port ------------------------------------------------------
 
@@ -70,6 +60,7 @@ export interface HttpRequest {
   readonly method?: string;
   readonly headers?: Record<string, string>;
   readonly body?: string;
+  readonly signal?: { readonly aborted: boolean };
 }
 
 /** The injected `fetch`. The platform's satisfies this structurally. */
@@ -105,29 +96,6 @@ export interface ApiFailure {
   readonly message: string;
 }
 
-/**
- * A `409` from a write route — its own arm, not a sixth {@link ApiErrorKind}.
- *
- * Every other failure is a dead end: the caller shows a message and stops. A
- * conflict is the opposite — it is the server handing back **the information
- * needed to continue**, and the editor's whole reload-or-overwrite prompt is
- * built from `conflict.current`. Folding it into `ApiFailure` would mean
- * either an optional field every caller has to remember is only sometimes
- * there, or a cast; a separate arm makes the payload's presence a fact the
- * compiler enforces once the caller has narrowed on `kind`.
- *
- * The `409` is therefore *not* an error in the sense the other five are, and
- * the type says so.
- */
-export interface ApiConflict {
-  readonly ok: false;
-  readonly kind: "conflict";
-  readonly status: 409;
-  readonly message: string;
-  /** The server's `409` body: the current note, or the taken slug. */
-  readonly conflict: ConflictPayload;
-}
-
 export interface ApiSuccess<T> {
   readonly ok: true;
   readonly data: T;
@@ -140,9 +108,6 @@ export interface ApiSuccess<T> {
 
 export type ApiResult<T> = ApiSuccess<T> | ApiFailure;
 
-/** The result of a write: as {@link ApiResult}, plus the `409` arm. */
-export type WriteResult<T> = ApiSuccess<T> | ApiFailure | ApiConflict;
-
 function success<T>(data: T, cached = false): ApiSuccess<T> {
   return { ok: true, data, cached };
 }
@@ -226,7 +191,7 @@ function isStringArray(value: unknown): value is string[] {
  *
  * `model.nodes` and `model.edges` are verified to be arrays and `stamp` to be
  * a string, because those three are what the columns index into and what the
- * SSE dedupe compares. Individual node fields are not walked: a per-node
+ * conditional request compares. Individual node fields are not walked: a per-node
  * validation pass on every refetch is real cost on a large graph, and a
  * malformed node degrades one row rather than crashing the app. The cutoff is
  * "what breaks the shell if absent", not "everything the type declares".
@@ -249,35 +214,9 @@ export function isViewNote(value: unknown): value is ViewNote {
   return isStringArray(value["tags"]);
 }
 
-/** `NotePayload` — a `ViewNote` plus the revision the editor saves against. */
+/** `NotePayload` — the note response wrapper. */
 export function isNotePayload(value: unknown): value is NotePayload {
-  return isObject(value) && typeof value["revision"] === "string" && isViewNote(value["note"]);
-}
-
-/** `DeleteNoteResult`. */
-export function isDeleteResult(value: unknown): value is DeleteNoteResult {
-  return isObject(value) && value["deleted"] === true;
-}
-
-/**
- * `ConflictPayload` — the `409` body.
- *
- * Checked to the depth the prompt renders, which for a `conflict` is the
- * whole nested note: the reload button writes `current.note` into the column
- * and the overwrite button sends `current.revision`, so a payload missing
- * either would produce a dialog whose buttons do nothing. Falling back to a
- * generic "server error" is the honest outcome for a malformed one.
- */
-export function isConflictPayload(value: unknown): value is ConflictPayload {
-  if (!isObject(value) || typeof value["error"] !== "string") return false;
-  if (value["reason"] === "collision") return typeof value["slug"] === "string";
-  if (value["reason"] !== "conflict") return false;
-  return isNotePayload(value["current"]);
-}
-
-/** `OkfFilePayload`. */
-export function isOkfFile(value: unknown): value is OkfFilePayload {
-  return isObject(value) && typeof value["path"] === "string" && typeof value["body"] === "string";
+  return isObject(value) && isViewNote(value["note"]);
 }
 
 /** `SearchPayload`. Hits are checked as an array; ranking tolerates junk. */
@@ -336,127 +275,26 @@ export async function fetchGraph(fetchImpl: FetchLike, previous: GraphPayload |
  * `GET /api/note/:slug`.
  *
  * The slug is percent-encoded here and traversal-checked *there* — the
- * server hands it to `resolveNotePath`, which rejects anything that is not a
- * flat slug. Doing our own check as well would be a second implementation to
+ * server hands it to `resolveNotePath`, which rejects unsafe slugs. Doing our
+ * own check as well would be a second implementation to
  * keep in sync, which is how traversal bugs are actually born (see
  * `routes.ts`). Encoding is still required, because an unencoded `#` or `?`
  * would silently truncate the path.
  *
- * Returns a {@link NotePayload}, not a bare `ViewNote`: the revision is read
- * **with** the note or not at all. Fetching it separately would leave a
- * window in which the two describe different states of the file, and a save
- * carrying a revision that does not match the body it was typed against is
- * worse than a save carrying none.
+ * Returns a {@link NotePayload}, not a bare `ViewNote`, so the response shape
+ * stays explicit at the HTTP boundary.
  */
 export function fetchNote(fetchImpl: FetchLike, slug: string): Promise<ApiResult<NotePayload>> {
   return request(fetchImpl, `/api/note/${encodeURIComponent(slug)}`, isNotePayload);
 }
 
-/** The URL for one note. One definition, so the four routes cannot disagree. */
-function noteUrl(slug: string, suffix = ""): string {
-  return `/api/note/${encodeURIComponent(slug)}${suffix}`;
-}
-
-/** A JSON write, as {@link HttpRequest}. */
-function writeInit(method: string, body: unknown): HttpRequest {
-  return { method, headers: { "content-type": "application/json" }, body: JSON.stringify(body) };
-}
-
-/**
- * Perform a write, decoding the `409` rather than flattening it.
- *
- * The generic {@link request} cannot serve here: it maps every non-2xx to an
- * {@link ApiFailure} with a message and no body, and the `409` body is the
- * entire point — it carries the note the user must choose between keeping
- * and discarding. So the conflict is intercepted before the status
- * classification and decoded through {@link isConflictPayload}.
- *
- * A `409` whose body does *not* decode falls through to a `server` failure.
- * That is deliberate rather than defensive: presenting a reload-or-overwrite
- * prompt built from a payload we could not read would offer the user two
- * buttons, at least one of which silently does nothing.
- */
-async function write<T>(
-  fetchImpl: FetchLike,
-  url: string,
-  guard: (value: unknown) => value is T,
-  init: HttpRequest,
-): Promise<WriteResult<T>> {
-  let response: HttpResponse;
-  try {
-    response = await fetchImpl(url, init);
-  } catch (error) {
-    return failure("network", 0, error instanceof Error ? error.message : "network request failed");
-  }
-
-  if (response.status === 409) {
-    let body: unknown;
-    try {
-      body = await response.json();
-    } catch {
-      return failure("malformed", 409, "response was not valid JSON");
-    }
-    if (!isConflictPayload(body)) return failure("malformed", 409, "response did not match the expected shape");
-    return { ok: false, kind: "conflict", status: 409, message: body.error, conflict: body };
-  }
-
-  if (!response.ok) return failure(classifyStatus(response.status), response.status, messageForStatus(response.status));
-
-  let body: unknown;
-  try {
-    body = await response.json();
-  } catch {
-    return failure("malformed", response.status, "response was not valid JSON");
-  }
-  if (!guard(body)) return failure("malformed", response.status, "response did not match the expected shape");
-  return success(body);
-}
-
-/**
- * `POST /api/note/:slug` — save (§11 P5.3, P5.5).
- *
- * `input.expectedRevision` is what makes a save safe, and omitting it is what
- * makes one an overwrite. Both are legitimate and neither is a default the
- * caller should stumble into, so this function takes the request verbatim
- * rather than deciding for it: `editor.model.ts` supplies the revision on a
- * normal save and drops it only after the user has looked at a conflict and
- * chosen to win.
- */
-export function saveNote(fetchImpl: FetchLike, slug: string, input: SaveNoteRequest): Promise<WriteResult<NotePayload>> {
-  return write(fetchImpl, noteUrl(slug), isNotePayload, writeInit("POST", input));
-}
-
-/**
- * `POST /api/note/:slug/rename`.
- *
- * A `409` here is a `collision`, not a `conflict` — the destination is
- * taken. The server refuses rather than uniquifying, because landing
- * somewhere other than where the user asked hides their mistake.
- */
-export function renameNote(fetchImpl: FetchLike, slug: string, target: string): Promise<WriteResult<NotePayload>> {
-  return write(fetchImpl, noteUrl(slug, "/rename"), isNotePayload, writeInit("POST", { slug: target }));
-}
-
-/** `DELETE /api/note/:slug`. Hard delete — the vault has no trash. */
-export function deleteNote(fetchImpl: FetchLike, slug: string): Promise<WriteResult<DeleteNoteResult>> {
-  return write(fetchImpl, noteUrl(slug), isDeleteResult, { method: "DELETE" });
-}
-
-/** `GET /api/okf/:rel`. Anchored under `<cwd>/.okf` by the server. */
-export function fetchOkfFile(fetchImpl: FetchLike, rel: string): Promise<ApiResult<OkfFilePayload>> {
-  // Per segment: `encodeURIComponent` would escape the separators of a
-  // relative path like `index/notes.md` into `%2F` and produce a 404.
-  const encoded = rel.split("/").map(encodeURIComponent).join("/");
-  return request(fetchImpl, `/api/okf/${encoded}`, isOkfFile);
-}
-
 /** `GET /api/search?q=`. An empty query is valid and returns no hits. */
-export function fetchSearch(fetchImpl: FetchLike, query: string): Promise<ApiResult<SearchPayload>> {
-  return request(fetchImpl, `/api/search?q=${encodeURIComponent(query)}`, isSearchPayload);
+export function fetchSearch(fetchImpl: FetchLike, query: string, signal?: { readonly aborted: boolean }): Promise<ApiResult<SearchPayload>> {
+  return request(fetchImpl, `/api/search?q=${encodeURIComponent(query)}`, isSearchPayload, signal === undefined ? undefined : { signal });
 }
 
 /**
- * `POST /api/open` — the only write in P1–P4.
+ * `POST /api/open` — hand the selected note to the user's editor.
  *
  * A missing note answers `404` with `{opened:false}`, which surfaces here as
  * a `missing` failure rather than a success carrying `false`. The status code

package/src/web/client/bootstrap.ts

@@ -1,7 +1,7 @@
 /**
- * Reading the page's bootstrap block (weave-workspace §5.3).
+ * Reading the page's bootstrap block.
  *
- * `page.ts` embeds `{cwd, vaultRoot, session}` as a nonce'd
+ * `page.ts` embeds `{cwd}` as a nonce'd
  * `<script type="application/json">` so the first paint knows where it is
  * without a round trip. This decodes it.
  *
@@ -21,24 +21,15 @@
 import type { Bootstrap } from "../shared/wire";
 
 /** What the client assumes when the page told it nothing. */
-export const EMPTY_BOOTSTRAP: Bootstrap = { cwd: "", vaultRoot: "", session: "" };
+export const EMPTY_BOOTSTRAP: Bootstrap = { cwd: "" };
 
 /**
- * Structural guard. Every field is a string, and all three are read.
- *
- * `session` is unused at P1 and checked anyway: it is what a later phase uses
- * to tell "I missed frames" from "this is a different server" (see its
- * `wire.ts` comment), and a guard that admits a bootstrap without it would
- * let that distinction fail silently the day it starts mattering.
+ * Structural guard for the one value the client reads.
  */
 function isBootstrap(value: unknown): value is Bootstrap {
   if (typeof value !== "object" || value === null) return false;
   const candidate = value as Record<string, unknown>;
-  return (
-    typeof candidate["cwd"] === "string" &&
-    typeof candidate["vaultRoot"] === "string" &&
-    typeof candidate["session"] === "string"
-  );
+  return typeof candidate["cwd"] === "string";
 }
 
 /**

package/src/web/client/context/context.model.ts

@@ -39,7 +39,7 @@
 import type { DetailLinkRow, ViewGraphModel } from "../../shared/view";
 import { deriveBacklinks, detailModel, listLabel } from "../../shared/view";
 import type { GraphPayload, WireGraphNode, WireNodeKind, WireNoteSource } from "../../shared/wire";
-import { isSessionNote, kindIcon, provenanceGlyph, provenanceTitle, viewModel } from "../tree/tree.model";
+import { kindIcon, provenanceGlyph, provenanceTitle, viewModel } from "../tree/tree.model";
 import type { IconName } from "../shell/icons.model";
 
 // --- rows and groups ---------------------------------------------------------------
@@ -83,7 +83,7 @@ export interface ContextModel {
    * A tag has a name, a count and a list of sibling notes; flattening that
    * into the same array as the link rows would mean a union type and a
    * discriminant check inside the component — which is a branch, in a `.tsx`,
-   * where §10 says branches cannot be covered. Two fields is the cheaper
+   * where  says branches cannot be covered. Two fields is the cheaper
    * shape.
    */
   readonly tags: readonly TagGroupRow[];
@@ -108,10 +108,8 @@ export const HEADINGS = { links: "LINKS", backlinks: "BACKLINKS", tags: "TAGS",
 /**
  * A row from a node. The rail's one place that reads a node's presentation.
  *
- * The icon follows the tree's rule, not the bare kind: a session-memory note
- * appears in LINKS just as often as in the tree, and the rail repeating the
- * tree's icon is how "this is the same thing" is communicated across the two
- * columns.
+ * The icon follows the tree's rule, so the same node is represented the same
+ * way in both columns.
  */
 export function rowFor(id: string, node: WireGraphNode, selectedId: string | null): ContextRow {
   return {
@@ -119,7 +117,7 @@ export function rowFor(id: string, node: WireGraphNode, selectedId: string | nul
     target: node.id,
     label: listLabel(node),
     kind: node.kind,
-    kindIcon: isSessionNote(node.id) ? "session" : kindIcon(node.kind),
+    kindIcon: kindIcon(node.kind),
     provenance: node.provenance,
     provenanceGlyph: provenanceGlyph(node.provenance),
     provenanceTitle: provenanceTitle(node.provenance),
@@ -186,7 +184,7 @@ function isMentionRow(row: DetailLinkRow): boolean {
  *
  * From `GraphPayload.tags` (§4.3) — the structured `tag → slugs` index — and
  * never from `WireGraphNode.detail.tags`, which is a comma-joined display
- * string that §4.2 forbids turning back into structure. The membership test is
+ * string that §4.3 forbids turning back into structure. The membership test is
  * therefore "does this tag's slug list contain mine", which is exact even for
  * a tag whose name contains a comma.
  *
@@ -277,7 +275,7 @@ function emptyRail(reason: string): ContextModel {
  * Build the rail.
  *
  * Empty groups are **omitted**, not rendered as headings over nothing. The
- * rail sits under the graph column in a fixed-height region (§1.2), so four
+ * rail sits under the graph column in a fixed-height region (§1.1), so four
  * headings with one row between them wastes the space that the one populated
  * group needed — and a heading with nothing under it reads as a load that
  * failed rather than as an absence.
@@ -332,7 +330,7 @@ export function contextModel(payload: GraphPayload | null, selectedId: string |
   return { subject: detail.label, groups, tags, tagsCount: tags.length, empty: null };
 }
 
-// --- counts and collapse (Tier 6, §8 P6.4) ---------------------------------------------
+// --- counts and collapse (Tier 6,  P6.4) ---------------------------------------------
 
 /**
  * A rail section as the component renders it: the heading's count, whether it
@@ -374,7 +372,7 @@ export function emptyRailToggles(): RailToggles {
  * A section longer than this opens collapsed.
  *
  * Eight is where a list stops being scannable without scrolling: the rail has
- * a fixed fraction of a fixed column (§1.2), so a MENTIONS section with forty
+ * a fixed fraction of a fixed column (§1.1), so a MENTIONS section with forty
  * entries would push the sections below it out of the viewport entirely —
  * which is how a rail meant to show *everything at once* ends up showing one
  * group. Under eight the rhythm would cost more than it saved.