@gmickel/gno 2.1.1 → 2.2.0

package/README.md

@@ -117,7 +117,7 @@ gno daemon --detach  # headless indexing + resident MCP gateway
 
 <!-- public-truth:current-version -->
 
-> Current source version: **v2.1.1**. See [CHANGELOG.md](./CHANGELOG.md).
+> Current source version: **v2.2.0**. See [CHANGELOG.md](./CHANGELOG.md).
 
 <!-- /public-truth -->
 

package/browser-extension/artifacts/gno-browser-clipper-v2.2.0.zip.sha256

@@ -0,0 +1 @@
+c2367d97e5599b41454becfa7d7e09ba9c1d5962096ce9e4f89b8794f9929f39  gno-browser-clipper-v2.2.0.zip

package/browser-extension/dist/manifest.json

@@ -21,5 +21,5 @@
   "content_security_policy": {
     "extension_pages": "script-src 'self'; object-src 'none'; connect-src http://127.0.0.1:*"
   },
-  "version": "2.1.1"
+  "version": "2.2.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmickel/gno",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "description": "Local semantic search for your documents. Index Markdown, PDF, and Office files with hybrid BM25 + vector search.",
   "keywords": [
     "embeddings",

package/spec/cli.md

@@ -2313,6 +2313,18 @@ MUST fail without an artifact. Encrypted CLI export requires `--passphrase`;
 the local API requires `encryptionPassphrase`. Neither sends that input to
 gno.sh. Export is a local operation, not hosted activation or deletion.
 
+New exports MUST assign each note a random lowercase UUIDv4 persisted in
+`publish-identities.json` beside the resolved config file (`--config` and
+`GNO_CONFIG_DIR` apply). The private registry keys canonical collection roots
+and source-relative paths, outside the disposable index. The collection root
+MUST be accessible for canonical-path resolution. V1 notes emit `id`;
+V2 spaces emit `noteIds` matching decrypted reader cards’ `noteId` values.
+Legacy artifacts without IDs remain valid. Registry corruption or write failure
+MUST fail export rather than reset IDs. Content/title edits, published route/slug
+changes, and index rebuilds preserve IDs for unchanged source paths. Moving a
+source file or collection root starts a new identity; no move inference or
+source-Markdown mutation is performed. Registry paths MUST NOT enter artifacts.
+
 Public V1 spaces MUST carry a `manifest` conforming to
 [`publish-artifact.schema.json`](./output-schemas/publish-artifact.schema.json).
 The manifest contains schema version `1.0`, a deterministic projection
@@ -2342,7 +2354,8 @@ insufficient). Asset-free exports omit `assets` /
 
 Secret-link and invite-only V1 spaces MUST NOT contain a manifest or agent
 capability field. Encrypted V2 spaces MUST contain only ciphertext parameters,
-the opaque secret token, route slug, source type, and encrypted visibility; no
+the opaque secret token, route slug, source type, encrypted visibility, and an
+optional unique `noteIds` UUIDv4 roster (1–5000 IDs); no
 plaintext manifest or evidence may appear outside the ciphertext. V2 builders
 MUST emit a closed projection, validate payload strings as non-empty bounded
 base64, require a positive safe-integer KDF iteration count, and bound the

package/spec/output-schemas/publish-artifact.schema.json

@@ -173,11 +173,16 @@
         ]
       }
     },
+    "noteId": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
     "note": {
       "type": "object",
       "additionalProperties": false,
       "required": ["markdown", "slug", "summary", "title"],
       "properties": {
+        "id": { "$ref": "#/definitions/noteId" },
         "markdown": { "type": "string" },
         "metadata": { "$ref": "#/definitions/metadata" },
         "slug": { "$ref": "#/definitions/slug" },
@@ -347,6 +352,13 @@
         "visibility"
       ],
       "properties": {
+        "noteIds": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 5000,
+          "uniqueItems": true,
+          "items": { "$ref": "#/definitions/noteId" }
+        },
         "encryptedPayload": {
           "type": "object",
           "additionalProperties": false,

package/src/cli/commands/publish.ts

@@ -98,6 +98,7 @@ export async function publishExport(
     const { artifact, assetSummary, warnings } = await exportPublishArtifact({
       collections,
       options: {
+        configPath: initResult.actualConfigPath,
         routeSlug: options.slug,
         encryptionPassphrase: options.encryptionPassphrase,
         summary: options.summary,

package/src/publish/artifact-validation.ts

@@ -6,6 +6,9 @@
 
 import { MAX_PUBLISH_UPLOAD_BYTES } from "./artifact-asset-contract";
 
+export const PUBLISH_NOTE_ID_PATTERN =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u;
+
 export const MAX_PUBLISH_SLUG_LENGTH = 80;
 /**
  * Ciphertext base64 character ceiling aligned to the 100 MiB final-envelope
@@ -33,6 +36,7 @@ const SOURCE_TYPES = new Set(["collection", "note"]);
 const READER_VISIBILITIES = new Set(["invite-only", "public", "secret-link"]);
 
 export interface ValidatedPublishNote {
+  id?: string;
   markdown: string;
   metadata?: Record<string, string | string[]>;
   slug: string;
@@ -51,6 +55,7 @@ export interface ValidatedPublishSpaceInput {
 }
 
 export interface ValidatedEncryptedPublishInput {
+  noteIds?: string[];
   encryptedPayload: {
     ciphertext: string;
     iterations: number;
@@ -158,6 +163,21 @@ const projectMetadata = (
   return result;
 };
 
+function requireNoteId(value: unknown): string {
+  if (typeof value !== "string" || !PUBLISH_NOTE_ID_PATTERN.test(value))
+    throw new Error("Publish note ID must be a lowercase UUIDv4");
+  return value;
+}
+
+function projectNoteIds(value: unknown): string[] {
+  if (!Array.isArray(value) || value.length < 1 || value.length > 5000)
+    throw new Error("noteIds must contain 1 to 5000 UUIDv4 IDs");
+  const ids = value.map(requireNoteId);
+  if (new Set(ids).size !== ids.length)
+    throw new Error("Duplicate publish note ID");
+  return ids;
+}
+
 const projectNote = (value: unknown, index: number): ValidatedPublishNote => {
   const field = `notes[${index}]`;
   const input = requireRecord(value, field);
@@ -168,6 +188,7 @@ const projectNote = (value: unknown, index: number): ValidatedPublishNote => {
     summary: requireString(input.summary, `${field}.summary`),
     title: requireNonblankString(input.title, `${field}.title`),
   };
+  if (input.id !== undefined) note.id = requireNoteId(input.id);
   if (metadata !== undefined) note.metadata = metadata;
   return note;
 };
@@ -181,6 +202,9 @@ export const validateAndProjectPublishSpaceInput = (
   }
 
   const notes = input.notes.map(projectNote);
+  const ids = notes.flatMap((note) => (note.id ? [note.id] : []));
+  if (new Set(ids).size !== ids.length)
+    throw new Error("Duplicate publish note ID");
   const noteSlugs = new Set<string>();
   for (const note of notes) {
     if (noteSlugs.has(note.slug)) {
@@ -246,6 +270,9 @@ export const validateAndProjectEncryptedPublishInput = (
   }
 
   return {
+    ...(input.noteIds === undefined
+      ? {}
+      : { noteIds: projectNoteIds(input.noteIds) }),
     encryptedPayload: {
       ciphertext: requireEncryptedCiphertext(payload.ciphertext),
       iterations,

package/src/publish/artifact.ts

@@ -68,6 +68,7 @@ export type PublishVisibility =
   | "secret-link";
 
 export interface PublishArtifactNote {
+  id?: string;
   markdown: string;
   metadata?: Record<string, string | string[]>;
   slug: string;
@@ -148,6 +149,7 @@ export interface EncryptedArtifactPayload {
 }
 
 export interface EncryptedPublishArtifactSpace {
+  noteIds?: string[];
   encryptedPayload: EncryptedArtifactPayload;
   routeSlug: string;
   secretToken: string;
@@ -441,6 +443,7 @@ export const buildPublishArtifact = (input: {
 };
 
 export const buildEncryptedPublishArtifact = (input: {
+  noteIds?: string[];
   egressLineage?: EgressLineage;
   encryptedPayload: EncryptedArtifactPayload;
   requiredCapabilities?: KnownPublishRequiredCapability[];
@@ -464,6 +467,9 @@ export const buildEncryptedPublishArtifact = (input: {
     source: validated.routeSlug,
     spaces: [
       {
+        ...(validated.noteIds === undefined
+          ? {}
+          : { noteIds: validated.noteIds }),
         encryptedPayload: validated.encryptedPayload,
         routeSlug: validated.routeSlug,
         secretToken: validated.secretToken,

package/src/publish/encrypted-export.ts

@@ -183,7 +183,7 @@ const deriveReaderPayload = (input: {
   const noteCards: ReaderNoteCard[] = input.notes.map((note) => {
     const blocks = parseMarkdownBlocks(note.markdown);
     return {
-      noteId: `${input.routeSlug}:${note.slug}`,
+      noteId: note.id ?? `${input.routeSlug}:${note.slug}`,
       slug: note.slug,
       title: note.title,
       excerpt: deriveExcerpt(note.summary, blocks),

package/src/publish/export-attachments.ts

@@ -197,6 +197,9 @@ export async function finalizeEncryptedArtifact(input: {
   const artifact = buildEncryptedPublishArtifact({
     egressLineage: input.egressLineage,
     encryptedPayload: encrypted.encryptedPayload,
+    ...(input.notes.every((note) => note.id !== undefined)
+      ? { noteIds: input.notes.map((note) => note.id!) }
+      : {}),
     requiredCapabilities:
       assets.length > 0 ? [BUNDLED_RASTER_ASSETS_CAPABILITY] : undefined,
     routeSlug: input.routeSlug,

package/src/publish/export-service.ts

@@ -34,12 +34,15 @@ import {
   sanitizeNoteMarkdown,
   type NoteBuildAccumulator,
 } from "./export-attachments";
+import { resolvePublishNoteIds } from "./identities";
 import {
   isPublishDisabledByFrontmatter,
   type SanitizeWarning,
 } from "./obsidian-sanitize";
 
 export interface PublishExportCoreOptions {
+  /** Actual loaded config file; defaults to the platform config directory. */
+  configPath?: string;
   encryptionPassphrase?: string;
   routeSlug?: string;
   summary?: string;
@@ -199,6 +202,7 @@ async function exportCollectionArtifact(
     preDedupRawBytes: 0,
   };
   const notes: PublishArtifactNote[] = [];
+  const sourceRelPaths: string[] = [];
 
   for (const doc of activeDocs) {
     if (!doc.mirrorHash) {
@@ -230,6 +234,7 @@ async function exportCollectionArtifact(
     acc.externalCount += sanitized.externalCount;
     acc.preDedupRawBytes += sanitized.preDedupRawBytes;
     acc.encodedAssetBytes += mergePayloads(acc.payloads, sanitized.payloads);
+    sourceRelPaths.push(doc.relPath);
     notes.push({
       markdown: sanitized.markdown,
       metadata: buildExportedMetadata(
@@ -268,6 +273,13 @@ async function exportCollectionArtifact(
     store,
   });
 
+  const noteIds = await resolvePublishNoteIds({
+    collectionRoot: collection.path,
+    sourceRelPaths,
+    configPath: options.configPath,
+  });
+  for (const [index, note] of notes.entries()) note.id = noteIds[index];
+
   if (visibility === "encrypted") {
     if (!options.encryptionPassphrase) {
       throw new Error(
@@ -321,6 +333,8 @@ async function exportDocumentArtifact(
 
   const collection =
     collections.find((entry) => entry.name === doc.collection) ?? null;
+  if (!collection)
+    throw new Error(`Collection not configured: ${doc.collection}`);
   const rawMarkdown = await loadDocumentMarkdown(store, doc);
   if (isPublishDisabledByFrontmatter(rawMarkdown)) {
     throw new Error(
@@ -362,7 +376,13 @@ async function exportDocumentArtifact(
     store,
   });
 
+  const [id] = await resolvePublishNoteIds({
+    collectionRoot: collection.path,
+    sourceRelPaths: [doc.relPath],
+    configPath: options.configPath,
+  });
   const note: PublishArtifactNote = {
+    id,
     markdown,
     metadata: buildExportedMetadata(doc, frontmatter, tags),
     slug,

package/src/publish/identities.ts

@@ -0,0 +1,153 @@
+/** Private durable publish identities, independent of the disposable index. */
+// node:fs/promises — canonical paths, permissions and atomic rename have no Bun equivalents.
+import {
+  chmod,
+  lstat,
+  mkdir,
+  realpath,
+  rename,
+  unlink,
+} from "node:fs/promises";
+// node:path — Bun has no path utilities.
+import { dirname, isAbsolute, join, normalize } from "node:path";
+
+import { getConfigPaths, toAbsolutePath } from "../config/paths";
+import { acquireWriteLock, type WriteLockHandle } from "../core/file-lock";
+import { PUBLISH_NOTE_ID_PATTERN } from "./artifact-validation";
+
+const IDENTITY_LOCK_TIMEOUT_MS = 5000;
+const IDENTITY_LOCK_RETRY_MS = 25;
+
+type Registry = { version: 1; identities: Record<string, string> };
+
+export function publishIdentityRegistryPath(configPath?: string): string {
+  return join(
+    configPath
+      ? dirname(toAbsolutePath(configPath))
+      : getConfigPaths().configDir,
+    "publish-identities.json"
+  );
+}
+
+function validateRegistry(value: unknown): Registry {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error("Invalid registry object");
+  const record = value as Record<string, unknown>;
+  if (
+    record.version !== 1 ||
+    Object.keys(record).length !== 2 ||
+    !record.identities ||
+    typeof record.identities !== "object" ||
+    Array.isArray(record.identities)
+  )
+    throw new Error("Invalid registry version or identities");
+  const identities = record.identities as Record<string, unknown>;
+  const ids = new Set<string>();
+  for (const [key, id] of Object.entries(identities)) {
+    const source: unknown = JSON.parse(key);
+    if (
+      !Array.isArray(source) ||
+      source.length !== 2 ||
+      !source.every((part) => typeof part === "string" && part.length > 0) ||
+      typeof id !== "string" ||
+      !PUBLISH_NOTE_ID_PATTERN.test(id) ||
+      ids.has(id)
+    )
+      throw new Error("Invalid or duplicate registry identity");
+    ids.add(id);
+  }
+  return value as Registry;
+}
+
+async function readRegistry(path: string): Promise<Registry> {
+  try {
+    const info = await lstat(path);
+    if (!info.isFile() || info.isSymbolicLink())
+      throw new Error("Registry must be a regular private file");
+    await chmod(path, 0o600);
+    return validateRegistry(await Bun.file(path).json());
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT")
+      return { version: 1, identities: {} };
+    throw new Error(
+      "Cannot read publish identity registry; restore a valid backup before exporting",
+      { cause: error }
+    );
+  }
+}
+
+async function acquireIdentityLock(path: string): Promise<WriteLockHandle> {
+  const deadline = performance.now() + IDENTITY_LOCK_TIMEOUT_MS;
+  // Zero-wait attempts avoid blocking the JS holder on SQLite's busy timeout.
+  // flock -w 0 and lockf -t 0 also mean immediate acquisition or failure.
+  let lock = await acquireWriteLock(path, 0);
+  while (!lock) {
+    const remaining = deadline - performance.now();
+    if (remaining <= 0)
+      throw new Error("Publish identity registry is busy; retry the export");
+    await Bun.sleep(Math.min(IDENTITY_LOCK_RETRY_MS, remaining));
+    lock = await acquireWriteLock(path, 0);
+  }
+  return lock;
+}
+
+/** Allocate a batch under one OS lock; publish IDs only after the private file commits. */
+export async function resolvePublishNoteIds(input: {
+  collectionRoot: string;
+  sourceRelPaths: string[];
+  configPath?: string;
+}): Promise<string[]> {
+  let root: string;
+  try {
+    root = await realpath(toAbsolutePath(input.collectionRoot));
+  } catch (cause) {
+    throw new Error(
+      "Collection root must exist and be accessible to resolve publish identities",
+      { cause }
+    );
+  }
+  const keys = input.sourceRelPaths.map((source) => {
+    const rel = normalize(source).replaceAll("\\", "/");
+    if (
+      !rel ||
+      rel === "." ||
+      rel === ".." ||
+      rel.startsWith("../") ||
+      isAbsolute(rel) ||
+      rel.includes("\0")
+    )
+      throw new Error(
+        "Publish source path must be relative to its collection root"
+      );
+    return JSON.stringify([root, rel]);
+  });
+  const path = publishIdentityRegistryPath(input.configPath);
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  const lock = await acquireIdentityLock(`${path}.lock`);
+  const temporaryPath = `${path}.tmp.${crypto.randomUUID()}`;
+  try {
+    const registry = await readRegistry(path);
+    let changed = false;
+    const ids = keys.map((key) => {
+      const existing = registry.identities[key];
+      if (existing) return existing;
+      const id = crypto.randomUUID();
+      registry.identities[key] = id;
+      changed = true;
+      return id;
+    });
+    if (changed) {
+      await Bun.write(temporaryPath, JSON.stringify(registry), { mode: 0o600 });
+      await rename(temporaryPath, path);
+    }
+    return ids;
+  } catch (error) {
+    throw new Error(
+      "Publish identity registry update failed; export aborted to preserve note identity",
+      { cause: error }
+    );
+  } finally {
+    await unlink(temporaryPath).catch(() => undefined);
+    await lock.release();
+  }
+}

package/src/serve/routes/api.ts

@@ -1266,7 +1266,8 @@ export async function handleEgressAuditPurge(
 export async function handlePublishExport(
   config: Config,
   store: SqliteAdapter,
-  req: Request
+  req: Request,
+  configPath?: string
 ): Promise<Response> {
   let body: PublishExportRequestBody;
   try {
@@ -1304,6 +1305,7 @@ export async function handlePublishExport(
     const { artifact, assetSummary, warnings } = await exportPublishArtifact({
       collections: config.collections,
       options: {
+        configPath,
         encryptionPassphrase: body.encryptionPassphrase,
         routeSlug: body.slug,
         summary: body.summary,

package/src/serve/server.ts

@@ -802,7 +802,8 @@ export async function startServer(
                 (dependencies.handlePublishExport ?? handlePublishExport)(
                   ctxHolder.config,
                   store,
-                  req
+                  req,
+                  runtime.actualConfigPath
                 )
               ),
               isDev

package/browser-extension/artifacts/gno-browser-clipper-v2.1.1.zip.sha256

@@ -1 +0,0 @@
-bf5fc1ea3dd699217e270114051b19e88b239265b3a33e395f5b5ba753bc9e47  gno-browser-clipper-v2.1.1.zip