@gmickel/gno 1.39.2 → 1.41.0

package/src/sdk/client.ts

@@ -38,7 +38,11 @@ import type {
   GnoMoveNoteOptions,
   GnoMultiGetOptions,
   GnoQueryOptions,
+  GnoRecallInput,
+  GnoRecallResult,
   GnoRefactorNoteResult,
+  GnoRememberInput,
+  GnoRememberResult,
   GnoRenameNoteApplyOptions,
   GnoRenameNoteOptions,
   GnoSearchOptions,
@@ -113,6 +117,11 @@ import {
   listKnowledgeChanges,
   type KnowledgeDeltaServiceResult,
 } from "../core/knowledge-delta";
+import {
+  MemoryError,
+  type MemoryErrorCode,
+  MemoryService,
+} from "../core/memory";
 import { resolveNoteCreatePlan } from "../core/note-creation";
 import { resolveNotePreset } from "../core/note-presets";
 import {
@@ -144,6 +153,7 @@ import {
 } from "../core/sections";
 import { normalizeStructuredQueryInput } from "../core/structured-query";
 import { parseAndValidateTagFilter } from "../core/tags";
+import { writeLeasePath } from "../core/write-lease";
 import {
   defaultSyncService,
   type SyncResult,
@@ -171,7 +181,7 @@ import {
   multiGetDocuments,
 } from "./documents";
 import { runEmbed } from "./embed";
-import { sdkError } from "./errors";
+import { type GnoSdkErrorCode, sdkError } from "./errors";
 
 interface OpenedClientState {
   config: Config;
@@ -295,6 +305,41 @@ async function resolveClientState(
   };
 }
 
+/** SDK error family per memory code; exhaustive so a new code fails to compile. */
+const MEMORY_ERROR_TO_SDK: Readonly<Record<MemoryErrorCode, GnoSdkErrorCode>> =
+  {
+    MEMORY_TEXT_REQUIRED: "VALIDATION",
+    MEMORY_TEXT_TOO_LARGE: "VALIDATION",
+    MEMORY_QUERY_REQUIRED: "VALIDATION",
+    MEMORY_BUDGET_INVALID: "VALIDATION",
+    MEMORY_COLLECTION_REQUIRED: "VALIDATION",
+    MEMORY_COLLECTION_NOT_FOUND: "NOT_FOUND",
+    MEMORY_COLLECTION_UNMANAGED: "VALIDATION",
+    MEMORY_SCOPES_REQUIRED: "VALIDATION",
+    MEMORY_SCOPES_INVALID: "VALIDATION",
+    MEMORY_IDENTITY_REQUIRED: "VALIDATION",
+    MEMORY_DECISION_INVALID: "VALIDATION",
+    MEMORY_PREDECESSOR_REQUIRED: "VALIDATION",
+    MEMORY_PREDECESSOR_NOT_FOUND: "NOT_FOUND",
+    MEMORY_PREDECESSOR_HASH_MISMATCH: "RUNTIME",
+    MEMORY_SUPERSEDE_CONFLICT: "RUNTIME",
+    MEMORY_SUPERSEDE_PROJECTION_FAILED: "RUNTIME",
+    MEMORY_FENCED_REPLAY: "VALIDATION",
+    MEMORY_FENCED_DERIVED: "VALIDATION",
+    MEMORY_WRITE_LEASE_BUSY: "RUNTIME",
+    MEMORY_SYNC_FAILED: "RUNTIME",
+    MEMORY_QUERY_FAILED: "RUNTIME",
+  };
+
+/** Map a core MemoryError onto the SDK error family; the memory code survives in `details.code`. */
+function toMemorySdkError(cause: unknown): unknown {
+  if (!(cause instanceof MemoryError)) return cause;
+  return sdkError(MEMORY_ERROR_TO_SDK[cause.code], cause.message, {
+    cause,
+    details: { code: cause.code },
+  });
+}
+
 class GnoClientImpl implements GnoClient {
   config: Config;
   readonly dbPath: string;
@@ -1581,6 +1626,54 @@ class GnoClientImpl implements GnoClient {
     };
   }
 
+  /**
+   * The memory service owns the shared write lease; the SDK never takes it.
+   * Embedding is best-effort: without a local model the service reports
+   * lexical-only matching/retrieval instead of failing.
+   */
+  private async withMemoryService<T>(
+    collection: string | undefined,
+    run: (service: MemoryService) => Promise<T>
+  ): Promise<T> {
+    this.assertOpen();
+    const ports = await this.createRuntimePorts({
+      embed: true,
+      collection: this.config.collections.some(
+        (candidate) => candidate.name === collection
+      )
+        ? collection
+        : undefined,
+    });
+    try {
+      return await run(
+        new MemoryService({
+          store: this.store,
+          config: this.config,
+          collections: this.config.collections,
+          lockPath: writeLeasePath(this.dbPath),
+          embedPort: ports.embedPort,
+          vectorIndex: ports.vectorIndex,
+        })
+      );
+    } catch (cause) {
+      throw toMemorySdkError(cause);
+    } finally {
+      await this.disposeRuntimePorts(ports);
+    }
+  }
+
+  async remember(input: GnoRememberInput): Promise<GnoRememberResult> {
+    return this.withMemoryService(input?.collection, (service) =>
+      service.remember(input)
+    );
+  }
+
+  async recall(input: GnoRecallInput): Promise<GnoRecallResult> {
+    return this.withMemoryService(input?.collection, (service) =>
+      service.recall(input)
+    );
+  }
+
   async capture(options: GnoCaptureOptions): Promise<GnoCaptureResult> {
     this.assertOpen();
     const collection = this.getCollections(options.collection)[0];

package/src/sdk/index.ts

@@ -58,6 +58,10 @@ export type {
   GnoMultiGetOptions,
   GnoMultiGetResult,
   GnoQueryOptions,
+  GnoRecallInput,
+  GnoRecallResult,
+  GnoRememberInput,
+  GnoRememberResult,
   GnoRenameNoteApplyOptions,
   GnoRenameNoteOptions,
   GnoProjectHintOptions,
@@ -76,7 +80,16 @@ export type {
   SectionTargetCreateSelector,
   SectionTargetResolveResult,
   SectionTargetV1,
+  MemoryCandidate,
+  MemoryFact,
+  MemoryRecallReceipt,
+  RecalledFact,
 } from "./types";
+export {
+  MemoryError,
+  type MemoryDecision,
+  type MemoryErrorCode,
+} from "../core/memory";
 export {
   ContextCapsuleContractError,
   type ContextCapsuleErrorCode,

package/src/sdk/types.ts

@@ -43,6 +43,16 @@ import type {
   KnowledgeImpactResult,
   ListKnowledgeChangesInput,
 } from "../core/knowledge-delta";
+import type {
+  MemoryCandidate,
+  MemoryFact,
+  MemoryRecallReceipt,
+  RecalledFact,
+  RecallInput,
+  RecallResult,
+  RememberInput,
+  RememberResult,
+} from "../core/memory";
 import type { NoteCollisionPolicy } from "../core/note-creation";
 import type { NotePresetId } from "../core/note-presets";
 import type {
@@ -245,6 +255,13 @@ export interface GnoCaptureOptions extends Omit<CaptureInput, "overwrite"> {}
 
 export type GnoCaptureResult = CaptureReceipt;
 
+/** Shared memory contract (identical on CLI, MCP, REST, and SDK). */
+export type GnoRememberInput = RememberInput;
+export type GnoRememberResult = RememberResult;
+export type GnoRecallInput = RecallInput;
+export type GnoRecallResult = RecallResult;
+export type { MemoryCandidate, MemoryFact, MemoryRecallReceipt, RecalledFact };
+
 export interface GnoCreateFolderOptions {
   collection: string;
   name: string;
@@ -370,6 +387,17 @@ export interface GnoClient {
   embed(options?: GnoEmbedOptions): Promise<GnoEmbedResult>;
   index(options?: GnoIndexOptions): Promise<GnoIndexResult>;
   capture(options: GnoCaptureOptions): Promise<GnoCaptureResult>;
+  /**
+   * Store one fact in a memory-managed collection, or propose candidates when
+   * `decision` is omitted. Requires caller + session identity and explicit
+   * scopes. Errors carry the stable memory code in `details.code`.
+   */
+  remember(input: GnoRememberInput): Promise<GnoRememberResult>;
+  /**
+   * Budgeted, cited recall of current facts in the caller's explicit scopes.
+   * The result carries a content-free fencing receipt.
+   */
+  recall(input: GnoRecallInput): Promise<GnoRecallResult>;
   createNote(options: GnoCreateNoteOptions): Promise<GnoCreateNoteResult>;
   createFolder(options: GnoCreateFolderOptions): Promise<GnoCreateFolderResult>;
   previewRenameNote(

package/src/serve/CLAUDE.md

@@ -71,12 +71,13 @@ Answer generation uses shared module to stay in sync with CLI:
 | --------------------- | ------ | ------------------------------------------ |
 | `/api/health`         | GET    | Health check                               |
 | `/api/status`         | GET    | Index stats, onboarding, health, bootstrap |
-| `/api/capabilities`   | GET    | Available features                         |
+| `/api/capabilities`   | GET    | Available features + `localClient`         |
 | `/api/collections`    | GET    | List collections                           |
 | `/api/publish/export` | POST   | Export gno.sh publish artifact JSON        |
 | `/api/docs`           | GET    | List documents                             |
 | `/api/doc`            | GET    | Get document content                       |
-| `/api/doc-asset`      | GET    | Original source file bytes (Range, HEAD)   |
+| `/api/doc-asset`      | GET    | Source file bytes (Range, HEAD, ETag/304)  |
+| `/api/docs/:id/reveal`| POST   | Reveal source on host (local client only)  |
 | `/vendor/pdfjs/*`     | GET    | Same-origin pdfjs worker/cmaps/fonts       |
 | `/api/search`         | POST   | BM25 search                                |
 | `/api/query`          | POST   | Hybrid search                              |
@@ -94,6 +95,17 @@ Answer generation uses shared module to stay in sync with CLI:
 - **AI Elements**: Conversation, Message, Sources, CodeBlock, Loader
 - **Tag Components**: TagInput, TagFacets (filter sidebar)
 - **Routing**: Simple hash-free SPA routing in App.tsx
+- **Server capabilities**: `public/lib/server-capabilities.ts` is the one
+  shared `ServerCapabilities` type (`localClient`) plus
+  `fetchServerCapabilities()`; a failed read counts as remote
+- **PDF viewer transport**: `public/lib/pdf-transport.ts` holds the tier
+  constants (`PDF_WHOLE_FILE_MAX_BYTES` = 8 MB, `PDF_RANGE_CHUNK_BYTES` =
+  1 MB) with no pdfjs import so Bun-side tooling can read them;
+  `hooks/use-pdf-document.ts` sends one same-origin `HEAD` per load to pick
+  the tier and falls back to ranged on any probe failure;
+  `hooks/use-pdf-pages.ts` publishes page slots from page 1 geometry and
+  corrects sizes and fit scales in one commit when the full pass lands
+  (fatal error = page 1 or document; later pages carry `slot.error`)
 
 ## Development
 
@@ -110,6 +122,14 @@ gno serve --port 3000
 - Binds to `127.0.0.1` only (no LAN exposure)
 - CSP headers on all responses
 - CORS protection on POST endpoints
+- Request locality (`request-locality.ts`): `localClient` is true only for a
+  loopback peer, a loopback `Host`, and no forwarding headers; the reveal
+  route refuses non-local clients with 403
+- HTTP caching: `/api/doc-asset` sends a strong `ETag` (size + mtime) with
+  `private, max-age=0, must-revalidate` and answers `If-None-Match` with 304
+  before Range handling; hashed SPA chunks (`/chunk-*.js|css`) get a one-year
+  `immutable` policy and a gzip body via `createPublicFetchFallback` in
+  `server.ts` (production only; the entry HTML and dev/HMR are untouched)
 - No external font/script loading — the PDF.js worker, cMaps, and standard fonts
   are served same-origin from the installed `pdfjs-dist` package via
   `/vendor/pdfjs/*`, so the CSP keeps `worker-src 'self'` and `font-src 'self'`

package/src/serve/clipper-security.ts

@@ -4,6 +4,7 @@ import type { HttpMcpPeerServer } from "../mcp/http-security";
 
 import { readClipperBoundedJson } from "./clipper-body";
 import { clipperSecurityErrorResponse } from "./clipper-security-errors";
+import { isLoopbackAddress } from "./request-locality";
 import { ReaderGate } from "./resident-admission";
 
 export { readClipperBoundedJson } from "./clipper-body";
@@ -126,7 +127,7 @@ function validateSameOriginEntry(origin: string): boolean {
 
 function isLoopbackHostname(hostname: string): boolean {
   if (hostname === "localhost") return true;
-  return isClipperLoopbackAddress(hostname.replace(/^\[|\]$/g, ""));
+  return isLoopbackAddress(hostname.replace(/^\[|\]$/g, ""));
 }
 
 function normalizedHeaderNames(headers: readonly string[]): string[] {
@@ -144,21 +145,6 @@ function normalizedHeaderNames(headers: readonly string[]): string[] {
   return [...new Set(normalized)];
 }
 
-export function isClipperLoopbackAddress(address: string): boolean {
-  const normalized = address.toLowerCase();
-  if (normalized === "::1") return true;
-  const mapped = normalized.startsWith("::ffff:")
-    ? normalized.slice("::ffff:".length)
-    : normalized;
-  const octets = mapped.split(".");
-  return (
-    octets.length === 4 &&
-    octets.every((octet) => /^\d{1,3}$/.test(octet)) &&
-    Number(octets[0]) === 127 &&
-    octets.every((octet) => Number(octet) <= 255)
-  );
-}
-
 export function parseClipperExtensionOrigin(
   origin: string
 ): { extensionId: string; origin: string } | null {
@@ -370,7 +356,7 @@ export class ClipperSecurityBoundary {
       }
     | ClipperSecurityFailure {
     const peer = server.requestIP(request);
-    if (!peer || !isClipperLoopbackAddress(peer.address)) {
+    if (!peer || !isLoopbackAddress(peer.address)) {
       return {
         ok: false,
         response: clipperSecurityErrorResponse("CLIPPER_FORBIDDEN"),

package/src/serve/public/components/pdf/PdfViewer.tsx

@@ -99,6 +99,69 @@ function StatePanel({
   );
 }
 
+const ERROR_EYEBROW: Record<PdfFallbackReason, string> = {
+  corrupt: "CANNOT RENDER",
+  password: "PASSWORD PROTECTED",
+  network: "COULD NOT LOAD",
+  bootstrap: "VIEWER UNAVAILABLE",
+};
+
+const PAGE_ERROR_BODY: Record<PdfFallbackReason, string> = {
+  corrupt: "This page could not be rendered.",
+  password: "This page is password protected.",
+  network: "This page could not be loaded from this session.",
+  bootstrap: "The PDF viewer could not render this page.",
+};
+
+type PdfPageErrorSlotProps = {
+  pageNumber: number;
+  width: number;
+  height: number;
+  error: PdfFallbackReason;
+  onMount: (pageNumber: number, el: HTMLElement | null) => void;
+};
+
+/**
+ * A later page whose geometry failed (R2): the page error state rendered in
+ * place of the page, at the slot's placeholder size so the scroll model and
+ * the visibility window keep their shape. Never fires the text fallback.
+ */
+function PdfPageErrorSlot({
+  pageNumber,
+  width,
+  height,
+  error,
+  onMount,
+}: PdfPageErrorSlotProps) {
+  const rootRef = useRef<HTMLDivElement | null>(null);
+
+  useEffect(() => {
+    onMount(pageNumber, rootRef.current);
+    return () => {
+      onMount(pageNumber, null);
+    };
+  }, [pageNumber, onMount]);
+
+  return (
+    <div
+      className="gno-pdf-page flex flex-col items-center justify-center gap-2 px-4 text-center"
+      data-page-error={error}
+      data-page-number={pageNumber}
+      data-testid={`pdf-page-${pageNumber}`}
+      ref={rootRef}
+      role="status"
+      style={{ width: width || undefined, height: height || undefined }}
+    >
+      <p className="font-mono text-[10px] text-muted-foreground/60 uppercase tracking-[0.15em]">
+        {ERROR_EYEBROW[error]}
+      </p>
+      <p className="text-[13px] text-foreground/90 leading-relaxed">
+        Page {pageNumber}: {PAGE_ERROR_BODY[error]}
+      </p>
+    </div>
+  );
+}
+
 function prefersReducedMotion(): boolean {
   if (
     typeof window === "undefined" ||
@@ -184,7 +247,11 @@ export function PdfViewer({
     containerWidth,
     containerHeight,
     genId,
+    scrollContainerRef: columnRef,
   });
+  // Fatal only: a document load failure or the hook's fatal error (page 1
+  // geometry, render-path acquisition). A later page's geometry failure rides
+  // on its slot and never reaches this path.
   const viewerError = status === "error" ? error : pages.error;
 
   // Fallback: exactly once per failed load/page attempt when extracted text exists.
@@ -400,7 +467,7 @@ export function PdfViewer({
           <StatePanel
             body="This PDF could not be rendered. Download the original to read it."
             downloadUrl={downloadUrl}
-            eyebrow="CANNOT RENDER"
+            eyebrow={ERROR_EYEBROW.corrupt}
             onRetry={handleRetry}
             role="alert"
             testId="pdf-state-corrupt"
@@ -411,7 +478,7 @@ export function PdfViewer({
           <StatePanel
             body="This PDF is password protected. Download the original to open it in a PDF reader."
             downloadUrl={downloadUrl}
-            eyebrow="PASSWORD PROTECTED"
+            eyebrow={ERROR_EYEBROW.password}
             role="alert"
             testId="pdf-state-password"
           />
@@ -421,7 +488,7 @@ export function PdfViewer({
           <StatePanel
             body="The document could not be loaded from this session. Try again, or download the original."
             downloadUrl={downloadUrl}
-            eyebrow="COULD NOT LOAD"
+            eyebrow={ERROR_EYEBROW.network}
             onRetry={handleRetry}
             role="alert"
             testId="pdf-state-network"
@@ -432,7 +499,7 @@ export function PdfViewer({
           <StatePanel
             body="The PDF viewer could not start in this window. Download the original to read it."
             downloadUrl={downloadUrl}
-            eyebrow="VIEWER UNAVAILABLE"
+            eyebrow={ERROR_EYEBROW.bootstrap}
             onRetry={handleRetry}
             role="alert"
             testId="pdf-state-bootstrap"
@@ -512,21 +579,32 @@ export function PdfViewer({
 
         {showProgressive ? (
           <div className="mx-auto flex w-fit flex-col items-center gap-6">
-            {pages.slots.map((slot) => (
-              <PdfPageView
-                key={slot.pageNumber}
-                active={slot.active}
-                doc={doc}
-                height={slot.height}
-                onMount={pages.observePage}
-                onInternalNavigate={goToPage}
-                onRender={pages.ensureRendered}
-                pageNumber={slot.pageNumber}
-                rendered={slot.rendered}
-                scale={pages.scale}
-                width={slot.width}
-              />
-            ))}
+            {pages.slots.map((slot) =>
+              slot.error ? (
+                <PdfPageErrorSlot
+                  key={slot.pageNumber}
+                  error={slot.error}
+                  height={slot.height}
+                  onMount={pages.observePage}
+                  pageNumber={slot.pageNumber}
+                  width={slot.width}
+                />
+              ) : (
+                <PdfPageView
+                  key={slot.pageNumber}
+                  active={slot.active}
+                  doc={doc}
+                  height={slot.height}
+                  onMount={pages.observePage}
+                  onInternalNavigate={goToPage}
+                  onRender={pages.ensureRendered}
+                  pageNumber={slot.pageNumber}
+                  rendered={slot.rendered}
+                  scale={pages.scale}
+                  width={slot.width}
+                />
+              )
+            )}
           </div>
         ) : null}
       </div>