@appsoftwareltd/etherpk-mcp 0.21.0 → 0.24.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/main.js CHANGED
@@ -43,6 +43,8 @@ import { createInterface as createInterface$1 } from "node:readline";
43
43
  // ../../packages/shared/src/managed-service.ts
44
44
  var ENTITLEMENT_AUDIENCE = "urn:etherpk:sync-entitlements";
45
45
  var ENTITLEMENT_SERVICE = "managed-sync";
46
+ /** The longest version retention period a statement or a server setting may ask for: ten years. */
47
+ var MAX_VERSION_RETENTION_DAYS = 3650;
46
48
  /**
47
49
  * Version-agnostic, like `isUuid` on the Server: any UUID version matches, so an id minted as a
48
50
  * uuidv7 is recognised as readily as a v4. One pattern, here, next to the claim it belongs to.
@@ -71,7 +73,14 @@ var entitlementLimitsSchema = z.strictObject({
71
73
  ownedStorageBytes: z.int().nonnegative(),
72
74
  playersPerGraph: z.int().nonnegative(),
73
75
  assetBytes: z.int().nonnegative(),
74
- assetChunks: z.int().nonnegative()
76
+ assetChunks: z.int().nonnegative(),
77
+ /**
78
+ * How many days a synced graph keeps its Document Versions, Deleted Documents and Deleted
79
+ * Assets (ADR 0184); 0 keeps none. Optional so that a statement issued without it stays
80
+ * readable: the Sync Server applies its own default when it is absent. An issuer sends it
81
+ * only to a Sync Server whose schema knows it, because the schema is strict.
82
+ */
83
+ versionRetentionDays: z.int().min(0).max(MAX_VERSION_RETENTION_DAYS).optional()
75
84
  });
76
85
  /**
77
86
  * Set, and only ever `true`, while the Billing Account's subscription has a payment outstanding
@@ -626,12 +635,100 @@ var ASSET_CHUNK_PLAINTEXT_BYTES = 4194304;
626
635
  function assetChunkCount(size) {
627
636
  return Math.max(1, Math.ceil(size / ASSET_CHUNK_PLAINTEXT_BYTES));
628
637
  }
638
+ var versionReasonSchema = z.enum([
639
+ "idle",
640
+ "before_delete",
641
+ "before_rename",
642
+ "before_replace_all",
643
+ "before_unprotect",
644
+ "before_restore",
645
+ "before_agent_write"
646
+ ]);
647
+ /** A version is one document's text, so it is bounded as a sync envelope is. */
648
+ var MAX_VERSION_ENVELOPE_BYTES = SYNC_PROTOCOL_LIMITS.maxEnvelopeBytes;
649
+ var isoTime = z.iso.datetime({ offset: true });
650
+ var envelope = z.string().min(1).refine((value) => decodedBase64UrlBytes(value) !== null, "Envelope is not valid base64url").refine((value) => (decodedBase64UrlBytes(value) ?? 0) <= MAX_VERSION_ENVELOPE_BYTES, "Envelope exceeds the version size limit");
651
+ z.strictObject({
652
+ versionId: z.uuid(),
653
+ epochId: z.int().nonnegative(),
654
+ reason: versionReasonSchema,
655
+ envelope
656
+ });
657
+ /**
658
+ * The upload's outcome. `skipped`: the server keeps no versions (a retention period of zero); the
659
+ * Client treats it as done.
660
+ */
661
+ var versionUploadResultSchema = z.strictObject({ status: z.enum([
662
+ "stored",
663
+ "exists",
664
+ "skipped"
665
+ ]) });
666
+ /**
667
+ * How long a graph keeps what Version History holds. `reduction` is set while a shorter period
668
+ * waits out its notice: until `from`, `retentionDays` (the longer period) still applies.
669
+ * `removalPaused` is set while the Owner's plan has lapsed: nothing is removed by age.
670
+ */
671
+ var versionPolicySchema = z.strictObject({
672
+ retentionDays: z.int().nonnegative(),
673
+ reduction: z.strictObject({
674
+ toDays: z.int().nonnegative(),
675
+ from: isoTime
676
+ }).nullable(),
677
+ removalPaused: z.boolean()
678
+ });
679
+ var versionListEntrySchema = z.strictObject({
680
+ versionId: z.uuid(),
681
+ createdAt: isoTime,
682
+ reason: versionReasonSchema,
683
+ bytes: z.int().nonnegative(),
684
+ epochId: z.int().nonnegative()
685
+ });
686
+ /** `GET …/docs/:docId/versions`: verified versions, newest first. */
687
+ var versionListSchema = z.strictObject({
688
+ versions: z.array(versionListEntrySchema),
689
+ policy: versionPolicySchema
690
+ });
691
+ /** `GET …/docs/:docId/versions/:versionId`: one sealed version. */
692
+ var versionEnvelopeSchema = z.strictObject({
693
+ versionId: z.uuid(),
694
+ createdAt: isoTime,
695
+ reason: versionReasonSchema,
696
+ epochId: z.int().nonnegative(),
697
+ envelope
698
+ });
699
+ /**
700
+ * `GET …/graphs/:graphId/deleted`. A Deleted Document is listed by its newest version, whose
701
+ * sealed identity gives the Client its name. `removeAt` is when the last thing keeping it goes,
702
+ * unless a Member removes it first; null while removal is paused.
703
+ */
704
+ var deletedItemsSchema = z.strictObject({
705
+ documents: z.array(z.strictObject({
706
+ docId: z.uuid(),
707
+ deletedAt: isoTime.nullable(),
708
+ newestVersionId: z.uuid(),
709
+ newestVersionAt: isoTime,
710
+ removeAt: isoTime.nullable()
711
+ })),
712
+ assets: z.array(z.strictObject({
713
+ assetId: z.uuid(),
714
+ size: z.int().nonnegative(),
715
+ deletedAt: isoTime,
716
+ removeAt: isoTime.nullable()
717
+ })),
718
+ policy: versionPolicySchema
719
+ });
629
720
  z.strictObject({
630
721
  /** Sync+ can be bought now. */
631
722
  billingEnabled: z.boolean(),
632
- /** The price as the account site writes it, currency included. Shown as text, never parsed. */
633
- priceDisplay: z.string().min(1).max(32).regex(/^[^\p{Cc}\p{Cf}<>]+$/u),
634
- billingInterval: z.enum(["month", "year"]),
723
+ /**
724
+ * The lowest price on offer, per month, as the account site writes it with its currency. A
725
+ * yearly price is given as a twelfth of the year. Shown as text, never parsed.
726
+ */
727
+ monthlyPriceDisplay: z.string().min(1).max(32).regex(/^[^\p{Cc}\p{Cf}<>]+$/u),
728
+ /** That price is charged once a year, so it reads "a month, billed yearly". */
729
+ billedYearly: z.boolean(),
730
+ /** Other tiers or billing periods cost more, so the price reads as "from". */
731
+ priceIsLowest: z.boolean(),
635
732
  /** Days of trial a first subscription starts with; 0 for none. */
636
733
  trialDays: z.number().int().min(0).max(366)
637
734
  });
@@ -723,7 +820,7 @@ function looksLikeAgentSetupCode(value) {
723
820
  }
724
821
  var package_default = {
725
822
  name: "@appsoftwareltd/etherpk-mcp",
726
- version: "0.21.0",
823
+ version: "0.24.0",
727
824
  license: "Elastic-2.0",
728
825
  description: "EtherPK Headless Client: an MCP server over a synced knowledge graph, run beside the agent on the user's own machine.",
729
826
  type: "module",
@@ -9741,7 +9838,7 @@ async function reachedWithin(promise, timeoutMs) {
9741
9838
  /** Longest line text kept. A longer line is still bookmarkable; its stored text is cut. */
9742
9839
  var MAX_TEXT = 2e3;
9743
9840
  var isString = (v) => typeof v === "string";
9744
- var optionalString = (v) => v === void 0 || isString(v) && v.length <= MAX_TEXT;
9841
+ var optionalString$1 = (v) => v === void 0 || isString(v) && v.length <= MAX_TEXT;
9745
9842
  /**
9746
9843
  * Bookmarks read from a backend, an import or a peer, kept only where well formed: anything else is
9747
9844
  * dropped rather than trusted. Over the cap the oldest go.
@@ -9758,7 +9855,7 @@ function sanitizeBookmarks(raw) {
9758
9855
  if (!isString(r.text) || r.text === "" || r.text.length > MAX_TEXT) continue;
9759
9856
  if (typeof r.line !== "number" || !Number.isInteger(r.line) || r.line < 0) continue;
9760
9857
  if (typeof r.createdAt !== "number" || !Number.isFinite(r.createdAt)) continue;
9761
- if (!optionalString(r.before) || !optionalString(r.after)) continue;
9858
+ if (!optionalString$1(r.before) || !optionalString$1(r.after)) continue;
9762
9859
  if (r.label !== void 0 && !(isString(r.label) && r.label.length <= 200)) continue;
9763
9860
  const bookmark = {
9764
9861
  id: r.id,
@@ -11223,7 +11320,8 @@ function createGraphSync(deps) {
11223
11320
  if (retained.has(docId)) attachPresence(docId, e);
11224
11321
  e.doc.on("update", (_update, origin) => {
11225
11322
  if (origin === CACHE_SEED) return;
11226
- for (const l of docUpdateListeners) l(docId);
11323
+ const local = origin !== REMOTE && origin !== SUPPRESSED && origin !== RECREATED;
11324
+ for (const l of docUpdateListeners) l(docId, local);
11227
11325
  });
11228
11326
  activate(docId, e);
11229
11327
  }
@@ -17840,6 +17938,40 @@ function withPublishFolder(folders, graphKey, publicationId, folder) {
17840
17938
  ...Object.keys(repositories).length > 0 ? { repositories } : {}
17841
17939
  };
17842
17940
  }
17941
+ // ../client/src/lib/sync/version-history/version-history-copy.ts
17942
+ var REASONS = {
17943
+ idle: "Edited",
17944
+ before_delete: "Before it was deleted",
17945
+ before_rename: "Before a rename",
17946
+ before_replace_all: "Before Replace all",
17947
+ before_unprotect: "Before protection was removed",
17948
+ before_restore: "Before a restore",
17949
+ before_agent_write: "Before an agent’s edit"
17950
+ };
17951
+ /** What made a version, in the person's terms. */
17952
+ function reasonLabel(reason) {
17953
+ return REASONS[reason];
17954
+ }
17955
+ new Intl.DateTimeFormat(void 0, {
17956
+ weekday: "short",
17957
+ day: "numeric",
17958
+ month: "short"
17959
+ });
17960
+ new Intl.DateTimeFormat(void 0, {
17961
+ weekday: "short",
17962
+ day: "numeric",
17963
+ month: "short",
17964
+ year: "numeric"
17965
+ });
17966
+ new Intl.DateTimeFormat(void 0, {
17967
+ hour: "2-digit",
17968
+ minute: "2-digit"
17969
+ });
17970
+ new Intl.DateTimeFormat(void 0, {
17971
+ day: "numeric",
17972
+ month: "long",
17973
+ year: "numeric"
17974
+ });
17843
17975
  // ../client/src/lib/document/protection/cipher-fence.ts
17844
17976
  /**
17845
17977
  * The `etherpk-cipher` fence as it appears in document *text* — finding one, reading what it holds
@@ -18419,6 +18551,8 @@ function createServerAssetStore(deps) {
18419
18551
  const base = deps.baseUrl.replace(/\/$/, "");
18420
18552
  const newAssetId = deps.newAssetId ?? (() => crypto.randomUUID());
18421
18553
  const objectUrls = [];
18554
+ /** Assets a person deleted in this session, which a reference coming back brings back (ADR 0184). */
18555
+ const deletedThisSession = /* @__PURE__ */ new Set();
18422
18556
  const keyring = keyringReader(deps.keyring);
18423
18557
  let dedup;
18424
18558
  const dedupSecret = (ring) => {
@@ -18483,6 +18617,14 @@ function createServerAssetStore(deps) {
18483
18617
  }
18484
18618
  return await res.json();
18485
18619
  }
18620
+ /** Ask the server to bring a Deleted Asset back (ADR 0184). */
18621
+ async function restoreDeleted(assetId) {
18622
+ const res = await f(`${base}/api/v1/sync/assets/${deps.graphId}/${assetId}/restore`, {
18623
+ method: "POST",
18624
+ headers: await authHeaders()
18625
+ });
18626
+ if (!res.ok) throw new Error(`asset restore failed: ${res.status}`);
18627
+ }
18486
18628
  /** Decrypt an asset's metadata under the graph's epoch keys. Rejects when it will not open or parse. */
18487
18629
  async function openMetadata(assetId, encryptedMetadata) {
18488
18630
  const { plaintext } = await openSymmetric({
@@ -18876,7 +19018,12 @@ function createServerAssetStore(deps) {
18876
19018
  return sending;
18877
19019
  },
18878
19020
  readBytes: (ref) => fetchAssetBytes(ref).catch((error) => error instanceof AssetUnavailableError && error.status !== void 0 || error instanceof AssetIntegrityError ? null : Promise.reject(error)),
19021
+ noteDeleted(assetId) {
19022
+ deletedThisSession.add(assetId);
19023
+ },
18879
19024
  async resolve(ref) {
19025
+ const id = assetIdFromRef(ref);
19026
+ if (id && deletedThisSession.delete(id)) restoreDeleted(id).catch(() => deletedThisSession.add(id));
18880
19027
  const asset = await fetchAssetBytes(ref);
18881
19028
  if (!asset) return null;
18882
19029
  const url = URL.createObjectURL(new Blob([asset.bytes], { type: asset.type }));
@@ -20131,11 +20278,16 @@ async function requireReadable(graph, asked) {
20131
20278
  function protectedDocument(asked) {
20132
20279
  return new ToolError("protected_document", `"${asked}" is a protected document. Its content is encrypted under a key this client never holds, so it cannot be changed here - the user can unlock it in EtherPK.`);
20133
20280
  }
20134
- /** The document an agent asked to change, with its text, refusing a hidden one as protected. */
20281
+ /**
20282
+ * The document an agent asked to change, with its text, refusing a hidden one as protected. On a
20283
+ * synced graph the session's first write to a document waits for a version of it (ADR 0184), so a
20284
+ * person can restore what it held before the agent's edit.
20285
+ */
20135
20286
  async function requireWritable(graph, asked) {
20136
20287
  const identity = requireIdentity(graph, asked);
20137
20288
  const text = await liveText(graph, identity);
20138
20289
  if (isHidden(hiddenKeys(graph), identity) || holdsEncryptedText(text)) throw protectedDocument(asked);
20290
+ await graph.versions?.beforeAgentWrite(identity.concept);
20139
20291
  return {
20140
20292
  identity,
20141
20293
  text
@@ -20192,6 +20344,51 @@ async function readDocument(graph, concept) {
20192
20344
  truncated: capped.truncated
20193
20345
  };
20194
20346
  }
20347
+ function requireVersions(graph) {
20348
+ if (!graph.versions) throw new ToolError("versions_unavailable", graph.backend.kind === "folder" ? "A folder graph keeps no version history in EtherPK: its history is whatever version control the folder has." : "This graph was opened without the Sync Server's HTTP API, so its version history cannot be read here.");
20349
+ return graph.versions;
20350
+ }
20351
+ /** A document's earlier versions, newest first (ADR 0184). Restoring one is done by a person in EtherPK. */
20352
+ async function listVersions(graph, concept) {
20353
+ await graph.store.refresh();
20354
+ const versions = requireVersions(graph);
20355
+ const { identity } = await requireReadable(graph, concept);
20356
+ const listed = await versions.list(identity.concept);
20357
+ if (!listed) throw notFound(concept);
20358
+ return {
20359
+ concept: identity.concept,
20360
+ versions: listed.versions.map((v) => ({
20361
+ version: v.versionId,
20362
+ createdAt: v.createdAt,
20363
+ madeBy: reasonLabel(v.reason)
20364
+ })),
20365
+ keptDays: listed.policy.retentionDays
20366
+ };
20367
+ }
20368
+ /** One earlier version's text (ADR 0184). */
20369
+ async function readVersion(graph, concept, version) {
20370
+ await graph.store.refresh();
20371
+ const versions = requireVersions(graph);
20372
+ const { identity } = await requireReadable(graph, concept);
20373
+ let read;
20374
+ try {
20375
+ read = await versions.read(identity.concept, version);
20376
+ } catch (error) {
20377
+ if (error.status === 404) throw new ToolError("not_found", `"${identity.concept}" has no version "${version}". list_versions names its versions.`);
20378
+ throw error;
20379
+ }
20380
+ if (!read) throw notFound(concept);
20381
+ if (holdsEncryptedText(read.text)) throw protectedDocument(concept);
20382
+ const capped = capText(read.text, READ_TEXT_CAP);
20383
+ const nameThen = read.identity.kind === "journal" ? read.identity.date ?? identity.concept : read.identity.title ?? identity.concept;
20384
+ return {
20385
+ concept: identity.concept,
20386
+ version,
20387
+ nameThen,
20388
+ text: capped.text,
20389
+ truncated: capped.truncated
20390
+ };
20391
+ }
20195
20392
  async function search(graph, args) {
20196
20393
  const query = args.query.trim();
20197
20394
  if (query === "") throw new ToolError("invalid_argument", "query must not be empty.");
@@ -22301,6 +22498,7 @@ function createMcpServer(source, info) {
22301
22498
  "Publishing: list_publications shows the publications this graph defines (a publication is a page whose frontmatter defines it - its outline is the site navigation) and the public documents none takes. A document is on a site when its frontmatter has public: true and names the publication in publications. create_publication and update_publication change the settings, and publish writes the site into the publish folder the user set for it on this machine with the etherpk-mcp publish command (the tool cannot choose a folder) and returns the report. publish with dryRun: true renders and reports without writing and needs no folder: run it after editing a publication's pages and fix what it names. Diagrams need a browser the user installs once with \"diagrams setup\".",
22302
22499
  "Themes: a publication's look is a theme - Mustache templates, a stylesheet, a script and a manifest. list_themes shows the bundled ones (read-only) and the graph's own. read_theme writes a theme's files to a folder on this machine to read and edit. customise_publication_theme copies a publication's bundled theme into the graph and points the publication at the copy (create_theme copies any theme). write_theme_file, delete_theme_file and import_theme_folder change a graph theme. preview_theme renders a theme to a folder (with screenshots when a browser is set up) to check before publish. For a snippet such as an analytics script, an include slot (update_publication includes, e.g. head) filled by a page may be lighter than a theme copy.",
22303
22500
  "Images and files are assets: upload_asset adds a file from this machine and returns the markdown to paste into a document. To put an image in a drawing, add a line to its excalidraw.drawing fence with the reference, width and height upload_asset returns: {\"type\":\"image\",\"customData\":{\"asset\":\"<reference>\"},\"x\":0,\"y\":0,\"width\":<width>,\"height\":<height>}. A shape added after it draws above it. Add lines only, and never edit or reorder the lines there. read_asset writes an asset to a local file you can open, and list_assets shows the assets documents reference. An asset is available only where a document you can read references it (or you uploaded it this session). read_asset, read_theme and preview_theme write under the graph's downloads directory and return the path - name a folder relative to it, never elsewhere.",
22501
+ "On a synced graph, your first edit to a document in a session keeps a version of it first. list_versions and read_version show a document's earlier versions. You cannot restore one: a person restores a version, or a deleted document or file, in EtherPK.",
22304
22502
  "The user documentation is at https://docs.etherpk.com."
22305
22503
  ].join("\n") });
22306
22504
  server.registerTool("list_documents", {
@@ -22319,6 +22517,19 @@ function createMcpServer(source, info) {
22319
22517
  description: "One document: its body as \"text\" (the markdown after any frontmatter block) and its frontmatter as the \"frontmatter\" object, minus title and aliases (its identity) and any publication definition. A protected document answers not_found, as a name nothing has. Long documents are cut and marked truncated: true.",
22320
22518
  inputSchema: { concept }
22321
22519
  }, async (args) => run((graph) => readDocument(graph, args.concept)));
22520
+ server.registerTool("list_versions", {
22521
+ title: "List a document's versions",
22522
+ description: "A synced document's earlier versions, newest first, each with when it was made and what made it (\"Edited\", \"Before a rename\", \"Before an agent's edit\"), and how many days the graph keeps them. Your first edit to a document in a session is preceded by a version of it. You cannot restore a version: tell the person, who restores it from the document's Version history in EtherPK.",
22523
+ inputSchema: { concept }
22524
+ }, async (args) => run((graph) => listVersions(graph, args.concept)));
22525
+ server.registerTool("read_version", {
22526
+ title: "Read a document version",
22527
+ description: "The whole text a synced document held at one earlier version (list_versions names them), frontmatter included, and the name it had then. Read-only: a person restores a version in EtherPK.",
22528
+ inputSchema: {
22529
+ concept,
22530
+ version: z.string().uuid().describe("A version id from list_versions.")
22531
+ }
22532
+ }, async (args) => run((graph) => readVersion(graph, args.concept, args.version)));
22322
22533
  server.registerTool("read_documents", {
22323
22534
  title: "Read several documents",
22324
22535
  description: `Up to 20 documents in one call, each as read_document returns it. A protected or unknown document is reported in its place as not_found rather than failing the call. Long texts are cut and marked truncated.`,
@@ -22771,7 +22982,8 @@ var sleep$2 = (ms) => new Promise((resolve) => setTimeout(resolve, ms).unref?.()
22771
22982
  /**
22772
22983
  * One session's view of the shared graph. Uploads are remembered per session, because a tool
22773
22984
  * refuses to read back an asset the agent did not upload or find in a document, and one agent's
22774
- * uploads say nothing about another's. A session whose `serve` passed --no-semantic gets a graph
22985
+ * uploads say nothing about another's. So are the documents a session has versioned before its
22986
+ * first write to them. A session whose `serve` passed --no-semantic gets a graph
22775
22987
  * with no semantic search, while the same graph builds its store for the sessions that want one.
22776
22988
  */
22777
22989
  function sessionGraph(graph, options) {
@@ -22780,7 +22992,8 @@ function sessionGraph(graph, options) {
22780
22992
  ...graph.assets ? { assets: {
22781
22993
  ...graph.assets,
22782
22994
  uploaded: /* @__PURE__ */ new Set()
22783
- } } : {}
22995
+ } } : {},
22996
+ ...graph.versions ? { versions: graph.versions.forSession() } : {}
22784
22997
  };
22785
22998
  if (!options.noSemantic) return view;
22786
22999
  const off = /* @__PURE__ */ new Error("Semantic search is off for this agent: serve was started with --no-semantic.");
@@ -26700,7 +26913,18 @@ function mergedText(texts) {
26700
26913
  function conceptOf(entry) {
26701
26914
  return entry.kind === "journal" ? entry.date ?? "" : entry.title ?? "";
26702
26915
  }
26916
+ /** A registry entry as a version records it. */
26917
+ function versionIdentityOf(entry) {
26918
+ return {
26919
+ kind: entry.kind,
26920
+ ...entry.title !== void 0 ? { title: entry.title } : {},
26921
+ ...entry.date !== void 0 ? { date: entry.date } : {},
26922
+ aliases: Array.isArray(entry.aliases) ? [...entry.aliases] : []
26923
+ };
26924
+ }
26703
26925
  function createServerDocumentStore(graph, options) {
26926
+ /** The store's options, by a name that a rename's own `options` parameter does not hide. */
26927
+ const storeOptions = options;
26704
26928
  const registry = graph.registry();
26705
26929
  /** Engines created between yields while snapshotting — small enough to keep frames free. */
26706
26930
  const ENGINE_BATCH = 100;
@@ -26712,6 +26936,8 @@ function createServerDocumentStore(graph, options) {
26712
26936
  * pages, short enough that a slow relay does not hold up a person who is typing.
26713
26937
  */
26714
26938
  const CREATE_CONFIRM_MS = 5e3;
26939
+ /** How long a delete waits to read a document nobody has open, for its version (ADR 0184). */
26940
+ const DELETE_VERSION_READ_MS = 5e3;
26715
26941
  const breathe = createBreather();
26716
26942
  const changeListeners = /* @__PURE__ */ new Set();
26717
26943
  const docsChangedListeners = /* @__PURE__ */ new Set();
@@ -26968,6 +27194,89 @@ function createServerDocumentStore(graph, options) {
26968
27194
  * document without a block keeps none. The caller has brought the text current first, or the
26969
27195
  * block would be written above a block still on its way.
26970
27196
  */
27197
+ /** What a restore writes to: the live document as it is, or a deleted one's returning entry. */
27198
+ function restoreTarget(docId, identity, name) {
27199
+ const live = registry.get(docId);
27200
+ if (live) return {
27201
+ live: true,
27202
+ entry: live
27203
+ };
27204
+ const returning = returningEntry(docId, identity, name);
27205
+ return "taken" in returning ? returning : {
27206
+ live: false,
27207
+ entry: returning.entry
27208
+ };
27209
+ }
27210
+ /**
27211
+ * Whether the document can be restored now: brought current, and, for a deleted one, known
27212
+ * here to be deleted. A deleted document's text is empty, which the relay confirms only online.
27213
+ */
27214
+ async function readyToRestore(docId, live, unconfirmed, timeoutMs) {
27215
+ if (unconfirmed && (live || !graph.isConnected())) return false;
27216
+ return live || untilDeleted(docId, timeoutMs);
27217
+ }
27218
+ /** Write a restore and answer the document's name: a live one is versioned first, a deleted one named again. */
27219
+ function writeRestore(docId, target, text) {
27220
+ if (target.live) storeOptions.recordVersion?.(docId, "before_restore");
27221
+ else registry.set(docId, target.entry);
27222
+ replaceWholeText(docId, text);
27223
+ writeBackIdentity(docId);
27224
+ return conceptOf(registry.get(docId) ?? target.entry);
27225
+ }
27226
+ /** One version of each document an operation is about to change (ADR 0184). */
27227
+ function versionEach(docIds, reason) {
27228
+ for (const docId of docIds) storeOptions.recordVersion?.(docId, reason);
27229
+ }
27230
+ /**
27231
+ * The registry entry a [[Deleted Document]] comes back under (ADR 0184): its version's identity,
27232
+ * or a page called `name`. Answers the name another document now holds instead, when it is
27233
+ * taken. An alias another document answers to is left off: the document is reachable by its name.
27234
+ */
27235
+ function returningEntry(docId, identity, name) {
27236
+ const entry = name !== void 0 ? {
27237
+ kind: "page",
27238
+ title: name.trim()
27239
+ } : { kind: identity.kind };
27240
+ if (name === void 0 && identity.title !== void 0) entry.title = identity.title;
27241
+ if (name === void 0 && identity.date !== void 0) entry.date = identity.date;
27242
+ const concept = conceptOf(entry);
27243
+ const holder = docIdFor(concept);
27244
+ if (holder && holder !== docId) return { taken: concept };
27245
+ if (name !== void 0) return { entry };
27246
+ const aliases = normaliseAliases(identity.aliases.filter((alias) => [void 0, docId].includes(docIdFor(alias))), concept);
27247
+ return { entry: aliases.length > 0 ? {
27248
+ ...entry,
27249
+ aliases
27250
+ } : entry };
27251
+ }
27252
+ /**
27253
+ * Wait until this device knows a document is deleted, asking the relay again, up to
27254
+ * `timeoutMs`. A restored document's text goes to the relay as its next generation (ADR 0043),
27255
+ * which this device sends only once it knows of the delete: an engine that caught up before
27256
+ * another device deleted the document still believes it active, and its write would be refused
27257
+ * as stale and dropped. A delete made here moments ago is still on its way to the relay.
27258
+ */
27259
+ async function untilDeleted(docId, timeoutMs) {
27260
+ const engine = graph.docSync(docId);
27261
+ const deadline = Date.now() + timeoutMs;
27262
+ while (engine.lifecycle() !== "deleted" && Date.now() < deadline) {
27263
+ if (engine.lifecycle() !== "deleting") engine.resync();
27264
+ await reachedWithin(engine.caughtUp(), Math.max(0, deadline - Date.now()));
27265
+ if (engine.lifecycle() !== "deleted") await new Promise((resolve) => setTimeout(resolve, 50));
27266
+ }
27267
+ return engine.lifecycle() === "deleted";
27268
+ }
27269
+ /**
27270
+ * Set a document's whole text in one transaction under the store's origin, which no undo
27271
+ * manager tracks: a restore is undone by restoring the version made before it.
27272
+ */
27273
+ function replaceWholeText(docId, text) {
27274
+ const ytext = graph.docSync(docId).doc.getText("content");
27275
+ ytext.doc.transact(() => {
27276
+ if (ytext.length > 0) ytext.delete(0, ytext.length);
27277
+ ytext.insert(0, text);
27278
+ }, STORE);
27279
+ }
26971
27280
  function writeBackIdentity(docId) {
26972
27281
  const entry = registry.get(docId);
26973
27282
  if (!entry) return;
@@ -27425,6 +27734,7 @@ function createServerDocumentStore(graph, options) {
27425
27734
  if (docIds.some((id, index) => texts[index] !== expected.get(id))) return "changed";
27426
27735
  const firstText = texts[0];
27427
27736
  const addition = mergedText(["", ...texts.slice(1)]);
27737
+ versionEach(docIds, "before_rename");
27428
27738
  if (addition !== "" && !firstText.endsWith(addition)) {
27429
27739
  const merged = mergedText(texts);
27430
27740
  const ytext = graph.docSync(first).doc.getText("content");
@@ -27565,6 +27875,34 @@ function createServerDocumentStore(graph, options) {
27565
27875
  materialised.release();
27566
27876
  }
27567
27877
  },
27878
+ versionSnapshot(docId) {
27879
+ const entry = registry.get(docId);
27880
+ if (!entry) return null;
27881
+ const engine = graph.docSync(docId);
27882
+ if (engine.lifecycle() === "seeding") return null;
27883
+ return {
27884
+ text: engine.doc.getText("content").toString(),
27885
+ identity: versionIdentityOf(entry)
27886
+ };
27887
+ },
27888
+ async restoreVersion(docId, version, restoreOptions) {
27889
+ const target = restoreTarget(docId, version.identity, restoreOptions?.name);
27890
+ if ("taken" in target) return {
27891
+ kind: "name-taken",
27892
+ name: target.taken
27893
+ };
27894
+ const timeoutMs = restoreOptions?.timeoutMs ?? COLD_CONTENT_TIMEOUT_MS;
27895
+ const materialised = await materialise([docId], timeoutMs);
27896
+ try {
27897
+ if (!await readyToRestore(docId, target.live, materialised.unconfirmed.length > 0, timeoutMs)) return { kind: "unconfirmed" };
27898
+ return {
27899
+ kind: "restored",
27900
+ concept: writeRestore(docId, target, version.text)
27901
+ };
27902
+ } finally {
27903
+ materialised.release();
27904
+ }
27905
+ },
27568
27906
  /**
27569
27907
  * Delete a document (ADR 0039): the registry entry goes AND the stored content is
27570
27908
  * removed server-side, so [[Storage Footprint]] drops immediately rather than waiting
@@ -27573,6 +27911,14 @@ function createServerDocumentStore(graph, options) {
27573
27911
  async deleteDocument(concept) {
27574
27912
  const docId = docIdFor(concept);
27575
27913
  if (!docId) return;
27914
+ if (options.recordVersion) {
27915
+ const entry = registry.get(docId);
27916
+ const read = (await this.readTexts([docId], { timeoutMs: DELETE_VERSION_READ_MS })).get(docId);
27917
+ if (entry && read?.settled) options.recordVersion(docId, "before_delete", {
27918
+ text: read.text,
27919
+ identity: versionIdentityOf(entry)
27920
+ });
27921
+ }
27576
27922
  creationClaims.delete(docId);
27577
27923
  await graph.deleteDoc(docId);
27578
27924
  registry.delete(docId);
@@ -27714,6 +28060,12 @@ function createServerDocumentStore(graph, options) {
27714
28060
  * (ADR 0038).
27715
28061
  */
27716
28062
  function applyRename(plan, options, readable) {
28063
+ const versioned = /* @__PURE__ */ new Set();
28064
+ const versionBefore = (docId) => {
28065
+ if (versioned.has(docId)) return;
28066
+ versioned.add(docId);
28067
+ storeOptions.recordVersion?.(docId, "before_rename");
28068
+ };
27717
28069
  for (const step of renameSteps(plan)) {
27718
28070
  if (!step.hasDocument) continue;
27719
28071
  const docId = docIdFor(step.from);
@@ -27736,6 +28088,8 @@ function createServerDocumentStore(graph, options) {
27736
28088
  body: absorbedBody,
27737
28089
  aliases
27738
28090
  });
28091
+ versionBefore(targetId);
28092
+ versionBefore(docId);
27739
28093
  survivor.doc.transact(() => {
27740
28094
  survivor.delete(0, survivor.length);
27741
28095
  survivor.insert(0, merged.body);
@@ -27749,6 +28103,7 @@ function createServerDocumentStore(graph, options) {
27749
28103
  writeBackIdentity(targetId);
27750
28104
  continue;
27751
28105
  }
28106
+ versionBefore(docId);
27752
28107
  const next = {
27753
28108
  ...entry,
27754
28109
  title: step.to
@@ -27779,6 +28134,7 @@ function createServerDocumentStore(graph, options) {
27779
28134
  });
27780
28135
  }
27781
28136
  for (const edit of edits) {
28137
+ versionBefore(edit.id);
27782
28138
  const ytext = graph.docSync(edit.id).doc.getText("content");
27783
28139
  ytext.doc.transact(() => {
27784
28140
  for (let i = edit.splices.length - 1; i >= 0; i--) {
@@ -27830,6 +28186,632 @@ async function listServerAssets(deps) {
27830
28186
  const { assets } = await res.json();
27831
28187
  return assets;
27832
28188
  }
28189
+ // ../client/src/lib/sync/version-history/version-api.ts
28190
+ /**
28191
+ * The Sync Server's Version History routes (ADR 0184), for one graph, as the Client and the
28192
+ * Headless Client call them: with a sync token for the graph, as the asset routes are called.
28193
+ *
28194
+ * Every answer is checked against the shared schema before it is used. A failed connection, or a
28195
+ * status that means "try again", rejects with {@link VersionApiUnavailableError}; any other
28196
+ * refusal with {@link VersionApiError}, carrying the server's code.
28197
+ */
28198
+ /** The server refused: `code` is its error code (`stale_epoch`, `quota_denied`, `owner_only` and so on). */
28199
+ var VersionApiError = class extends Error {
28200
+ status;
28201
+ code;
28202
+ quotaCode;
28203
+ constructor(message, status, code, quotaCode) {
28204
+ super(message);
28205
+ this.status = status;
28206
+ this.code = code;
28207
+ this.quotaCode = quotaCode;
28208
+ this.name = "VersionApiError";
28209
+ }
28210
+ };
28211
+ /** The server could not be reached, or asked to be tried again later. */
28212
+ var VersionApiUnavailableError = class extends Error {
28213
+ constructor(message, options) {
28214
+ super(message, options);
28215
+ this.name = "VersionApiUnavailableError";
28216
+ }
28217
+ };
28218
+ var TRANSIENT = /* @__PURE__ */ new Set([
28219
+ 408,
28220
+ 425,
28221
+ 429,
28222
+ 500,
28223
+ 502,
28224
+ 503,
28225
+ 504
28226
+ ]);
28227
+ /** The error a refused answer stands for, from its status and its JSON body. */
28228
+ async function refusalFrom(res) {
28229
+ if (TRANSIENT.has(res.status)) return new VersionApiUnavailableError(`The sync server could not answer just now (HTTP ${res.status}).`);
28230
+ const body = await res.json().catch(() => null);
28231
+ if (body?.error === "quota_denied") return new VersionApiError("The graph owner’s plan does not allow this now.", res.status, "quota_denied", body.code);
28232
+ const error = typeof body?.error === "object" ? body.error : void 0;
28233
+ return new VersionApiError(error?.message ?? `The sync server refused (HTTP ${res.status}).`, res.status, error?.code);
28234
+ }
28235
+ function createVersionApi(deps) {
28236
+ const f = deps.fetch ?? ((input, init) => fetch(input, init));
28237
+ const base = deps.baseUrl.replace(/\/$/, "");
28238
+ const graph = `${base}/api/v1/sync/graphs/${deps.graphId}`;
28239
+ const docVersions = (docId) => `${graph}/docs/${docId}/versions`;
28240
+ const asset = (assetId) => `${base}/api/v1/sync/assets/${deps.graphId}/${assetId}`;
28241
+ async function send(url, init, fresh) {
28242
+ const headers = { "x-sync-token": await deps.syncToken(fresh ? { force: true } : void 0) };
28243
+ if (init.body !== void 0) headers["Content-Type"] = "application/json";
28244
+ try {
28245
+ return await f(url, {
28246
+ method: init.method ?? "GET",
28247
+ headers,
28248
+ body: init.body === void 0 ? void 0 : JSON.stringify(init.body)
28249
+ });
28250
+ } catch (cause) {
28251
+ if (cause instanceof DOMException && cause.name === "AbortError") throw cause;
28252
+ throw new VersionApiUnavailableError("The sync server could not be reached.", { cause });
28253
+ }
28254
+ }
28255
+ /** One request; a 401 is tried once more with a freshly minted token, as the asset routes are. */
28256
+ async function call(url, init = {}) {
28257
+ let res = await send(url, init, false);
28258
+ if (res.status === 401) res = await send(url, init, true);
28259
+ if (res.ok) return res.json();
28260
+ throw await refusalFrom(res);
28261
+ }
28262
+ return {
28263
+ async upload(docId, version) {
28264
+ const answer = await call(docVersions(docId), {
28265
+ method: "POST",
28266
+ body: {
28267
+ versionId: version.versionId,
28268
+ epochId: version.epochId,
28269
+ reason: version.reason,
28270
+ envelope: toBase64Url(version.envelope)
28271
+ }
28272
+ });
28273
+ return versionUploadResultSchema.parse(answer).status;
28274
+ },
28275
+ async verify(docId, versionId) {
28276
+ await call(`${docVersions(docId)}/${versionId}/verified`, { method: "POST" });
28277
+ },
28278
+ async list(docId) {
28279
+ return versionListSchema.parse(await call(docVersions(docId)));
28280
+ },
28281
+ async get(docId, versionId) {
28282
+ const { envelope, ...entry } = versionEnvelopeSchema.parse(await call(`${docVersions(docId)}/${versionId}`));
28283
+ return {
28284
+ entry,
28285
+ envelope: fromBase64Url(envelope)
28286
+ };
28287
+ },
28288
+ async removeDocument(docId) {
28289
+ const answer = await call(docVersions(docId), { method: "DELETE" });
28290
+ return typeof answer.removed === "number" ? answer.removed : 0;
28291
+ },
28292
+ async deleted() {
28293
+ return deletedItemsSchema.parse(await call(`${graph}/deleted`));
28294
+ },
28295
+ async removeAll() {
28296
+ const answer = await call(`${graph}/kept`, { method: "DELETE" });
28297
+ return {
28298
+ versions: typeof answer.versions === "number" ? answer.versions : 0,
28299
+ assets: typeof answer.assets === "number" ? answer.assets : 0
28300
+ };
28301
+ },
28302
+ async policy() {
28303
+ return versionPolicySchema.parse(await call(`${graph}/version-policy`));
28304
+ },
28305
+ async restoreAsset(assetId) {
28306
+ const outcome = (await call(`${asset(assetId)}/restore`, { method: "POST" })).outcome;
28307
+ return outcome === "restored" || outcome === "live" ? outcome : "gone";
28308
+ },
28309
+ async assetExists(assetId) {
28310
+ try {
28311
+ await call(asset(assetId));
28312
+ return true;
28313
+ } catch (error) {
28314
+ if (error instanceof VersionApiError && error.status === 404) return false;
28315
+ throw error;
28316
+ }
28317
+ },
28318
+ async removeAssetForGood(assetId) {
28319
+ try {
28320
+ await call(`${asset(assetId)}?forGood=1`, { method: "DELETE" });
28321
+ } catch (error) {
28322
+ if (error instanceof VersionApiError && error.status === 404) return;
28323
+ throw error;
28324
+ }
28325
+ }
28326
+ };
28327
+ }
28328
+ // ../client/src/lib/sync/version-history/version-payload.ts
28329
+ /**
28330
+ * What a [[Document Version]] holds, and how it is sealed (ADR 0184).
28331
+ *
28332
+ * The plaintext is the document's whole text, frontmatter included, and its identity as the
28333
+ * registry held it: kind, name or day, and aliases. A delete removes the identity from the
28334
+ * registry, and restoring a deleted document needs it back.
28335
+ *
28336
+ * Sealed with the graph's current epoch key in the same envelope as every other synced byte. The
28337
+ * AAD binds the envelope to its graph, document and version id, so a server cannot hand one
28338
+ * document's version to another, or relabel one version as another.
28339
+ */
28340
+ var VersionPayloadError = class extends Error {};
28341
+ function encodeVersionPayload(payload) {
28342
+ return new TextEncoder().encode(JSON.stringify(payload));
28343
+ }
28344
+ var optionalString = (value) => value === void 0 || typeof value === "string";
28345
+ function isIdentity(value) {
28346
+ const identity = value;
28347
+ return typeof identity === "object" && identity !== null && (identity.kind === "journal" || identity.kind === "page") && optionalString(identity.title) && optionalString(identity.date) && Array.isArray(identity.aliases) && identity.aliases.every((alias) => typeof alias === "string");
28348
+ }
28349
+ function isPayload(value) {
28350
+ const candidate = value;
28351
+ return typeof candidate === "object" && candidate !== null && candidate.v === 1 && typeof candidate.text === "string" && isIdentity(candidate.identity);
28352
+ }
28353
+ /** Read a payload, refusing anything not exactly this shape: a restore must never guess. */
28354
+ function decodeVersionPayload(bytes) {
28355
+ let value;
28356
+ try {
28357
+ value = JSON.parse(new TextDecoder().decode(bytes));
28358
+ } catch (cause) {
28359
+ throw new VersionPayloadError("The version could not be read", { cause });
28360
+ }
28361
+ if (!isPayload(value)) throw new VersionPayloadError("The version is in a form this Client does not read");
28362
+ const { kind, title, date, aliases } = value.identity;
28363
+ return {
28364
+ v: 1,
28365
+ identity: {
28366
+ kind,
28367
+ aliases: [...aliases],
28368
+ ...title !== void 0 ? { title } : {},
28369
+ ...date !== void 0 ? { date } : {}
28370
+ },
28371
+ text: value.text
28372
+ };
28373
+ }
28374
+ function versionAad(graphId, docId, versionId) {
28375
+ return contextAad("version", `graph:${graphId}`, `doc:${docId}`, `version:${versionId}`);
28376
+ }
28377
+ async function sealVersion(opts) {
28378
+ const epoch = currentEpoch(opts.keyring);
28379
+ return {
28380
+ envelope: await sealSymmetric({
28381
+ key: epoch.key,
28382
+ epochId: epoch.epochId,
28383
+ plaintext: encodeVersionPayload(opts.payload),
28384
+ aad: versionAad(opts.graphId, opts.docId, opts.versionId)
28385
+ }),
28386
+ epochId: epoch.epochId
28387
+ };
28388
+ }
28389
+ /** Open a version under whichever epoch sealed it; rejects when it will not open or read. */
28390
+ async function openVersion(opts) {
28391
+ const { plaintext } = await openSymmetric({
28392
+ keyForEpoch: (epochId) => keyForEpoch(opts.keyring, epochId),
28393
+ envelope: opts.envelope,
28394
+ aad: versionAad(opts.graphId, opts.docId, opts.versionId)
28395
+ });
28396
+ return decodeVersionPayload(plaintext);
28397
+ }
28398
+ // ../client/src/lib/sync/version-history/version-history.ts
28399
+ var UUID = "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}";
28400
+ /**
28401
+ * The asset ids a document's text references: every `assets/` path whose file name carries an id,
28402
+ * which is how a synced graph writes a reference (`assets/<stem>.<id>.<ext>`). Each once.
28403
+ */
28404
+ function assetIdsReferencedIn(text) {
28405
+ const ids = /* @__PURE__ */ new Set();
28406
+ const pattern = new RegExp(`assets/[^\\s)\\]"'|]*?(?:^|[./])(${UUID})(?:\\.[A-Za-z0-9]+)?`, "gi");
28407
+ for (const match of text.matchAll(pattern)) ids.add(match[1].toLowerCase());
28408
+ return [...ids];
28409
+ }
28410
+ function createVersionHistory(deps) {
28411
+ const keyring = keyringReader(deps.keyring);
28412
+ const open = async (docId, versionId, envelope) => openVersion({
28413
+ keyring: keyring(),
28414
+ graphId: deps.graphId,
28415
+ docId,
28416
+ versionId,
28417
+ envelope
28418
+ });
28419
+ async function read(docId, versionId) {
28420
+ const { envelope } = await deps.api.get(docId, versionId);
28421
+ return open(docId, versionId, envelope);
28422
+ }
28423
+ return {
28424
+ documentIdOf: (concept) => deps.store.documentIdOf(concept),
28425
+ async missingAssets(text) {
28426
+ const ids = assetIdsReferencedIn(text);
28427
+ const held = await Promise.all(ids.map((id) => deps.api.assetExists(id).catch(() => true)));
28428
+ return ids.filter((_id, index) => !held[index]);
28429
+ },
28430
+ recordBefore(concept, reason) {
28431
+ const docId = deps.store.documentIdOf(concept);
28432
+ if (docId) deps.recorder.record(docId, reason).catch(() => void 0);
28433
+ },
28434
+ settle(concept) {
28435
+ if (concept === void 0) return deps.recorder.settle();
28436
+ const docId = deps.store.documentIdOf(concept);
28437
+ if (docId) deps.recorder.settle(docId);
28438
+ },
28439
+ policy: () => deps.api.policy(),
28440
+ list: (docId) => deps.api.list(docId),
28441
+ read,
28442
+ async restore(docId, versionId, options) {
28443
+ if ((await deps.api.policy()).removalPaused) return { kind: "read-only" };
28444
+ const version = await read(docId, versionId);
28445
+ const outcome = await deps.store.restoreVersion(docId, {
28446
+ text: version.text,
28447
+ identity: version.identity
28448
+ }, options);
28449
+ if (outcome.kind !== "restored") return outcome;
28450
+ const missingAssets = [];
28451
+ for (const assetId of assetIdsReferencedIn(version.text)) if (await deps.api.restoreAsset(assetId).catch(() => "gone") === "gone") missingAssets.push(assetId);
28452
+ await deps.recorder.flush();
28453
+ return {
28454
+ ...outcome,
28455
+ missingAssets
28456
+ };
28457
+ },
28458
+ async deleted() {
28459
+ const listing = await deps.api.deleted();
28460
+ return {
28461
+ documents: await Promise.all(listing.documents.map(async (entry) => {
28462
+ const identity = await read(entry.docId, entry.newestVersionId).then((version) => version.identity).catch(() => null);
28463
+ return {
28464
+ docId: entry.docId,
28465
+ identity,
28466
+ deletedAt: entry.deletedAt,
28467
+ newestVersionId: entry.newestVersionId,
28468
+ removeAt: entry.removeAt
28469
+ };
28470
+ })),
28471
+ assets: await Promise.all(listing.assets.map(async (entry) => ({
28472
+ ...entry,
28473
+ name: await deps.assetName?.(entry.assetId).catch(() => null) ?? null
28474
+ }))),
28475
+ policy: listing.policy
28476
+ };
28477
+ },
28478
+ async removeHistory(docId) {
28479
+ await deps.recorder.forget(docId);
28480
+ await deps.api.removeDocument(docId);
28481
+ },
28482
+ removeAll: () => deps.api.removeAll(),
28483
+ restoreAsset: (assetId) => deps.api.restoreAsset(assetId),
28484
+ removeAssetForGood: (assetId) => deps.api.removeAssetForGood(assetId),
28485
+ async documentProtected(docId) {
28486
+ await deps.recorder.forget(docId);
28487
+ await deps.api.removeDocument(docId);
28488
+ }
28489
+ };
28490
+ }
28491
+ // ../client/src/lib/sync/version-history/version-recorder.ts
28492
+ /**
28493
+ * Makes a graph's [[Document Version]]s on this device (ADR 0184).
28494
+ *
28495
+ * Two kinds:
28496
+ *
28497
+ * - **Before an operation.** A delete, a rename or merge, a replace-all, removing protection, a
28498
+ * restore and an agent's first write each call {@link VersionRecorder.record} first. The text is
28499
+ * read at that moment, before the operation changes it, sealed, and put in the outbox. The
28500
+ * operation does not wait on the network: the outbox sends the version straight after, or when
28501
+ * the connection returns.
28502
+ * - **Idle.** After a local edit, once the document has had no edit for `idleMs` and at least
28503
+ * ten minutes have passed since this device's last version of it. Edits still waiting when the
28504
+ * document is closed, the page is left or the graph closes are kept then, through
28505
+ * {@link VersionRecorder.settle}: otherwise the last edits of a session would be in no version
28506
+ * until the next session's first edit had already changed them.
28507
+ *
28508
+ * A sent version is read back and opened before it is marked verified: the server lists only
28509
+ * verified versions, so one that cannot be read never appears.
28510
+ */
28511
+ var IDLE_MS = 3e4;
28512
+ var RETRY_MS = 6e4;
28513
+ var VersionMismatchError = class extends Error {};
28514
+ function createVersionRecorder(deps) {
28515
+ const keyring = keyringReader(deps.keyring);
28516
+ const now = deps.now ?? Date.now;
28517
+ const setTimer = deps.setTimer ?? ((run, ms) => setTimeout(run, ms));
28518
+ const clearTimer = deps.clearTimer ?? ((timer) => clearTimeout(timer));
28519
+ const newVersionId = deps.newVersionId ?? (() => crypto.randomUUID());
28520
+ const idleMs = deps.idleMs ?? IDLE_MS;
28521
+ const gapMs = deps.gapMs ?? 6e5;
28522
+ const retryMs = deps.retryMs ?? RETRY_MS;
28523
+ const documents = /* @__PURE__ */ new Map();
28524
+ let retryTimer = null;
28525
+ let flushing = null;
28526
+ /** Versions read and being sealed, which a flush waits for so it sends them too. */
28527
+ const sealing = /* @__PURE__ */ new Set();
28528
+ let flushAgain = false;
28529
+ let disposed = false;
28530
+ const stateOf = (docId) => {
28531
+ let state = documents.get(docId);
28532
+ if (!state) {
28533
+ state = {
28534
+ dirty: false,
28535
+ timer: null,
28536
+ lastRecordedAt: Number.NEGATIVE_INFINITY
28537
+ };
28538
+ documents.set(docId, state);
28539
+ }
28540
+ return state;
28541
+ };
28542
+ async function record(docId, reason, options = {}) {
28543
+ if (disposed) return "unreadable";
28544
+ const snapshot = options.snapshot ?? deps.source.read(docId);
28545
+ if (!snapshot) return "unreadable";
28546
+ const payload = {
28547
+ v: 1,
28548
+ identity: snapshot.identity,
28549
+ text: snapshot.text
28550
+ };
28551
+ const versionId = newVersionId();
28552
+ const queuedAt = now();
28553
+ stateOf(docId).lastRecordedAt = queuedAt;
28554
+ const queued = (async () => {
28555
+ const sealed = await sealVersion({
28556
+ keyring: keyring(),
28557
+ graphId: deps.graphId,
28558
+ docId,
28559
+ versionId,
28560
+ payload
28561
+ });
28562
+ await deps.outbox.put(deps.graphId, {
28563
+ docId,
28564
+ versionId,
28565
+ reason,
28566
+ epochId: sealed.epochId,
28567
+ envelope: sealed.envelope,
28568
+ queuedAt
28569
+ });
28570
+ })();
28571
+ sealing.add(queued);
28572
+ try {
28573
+ await queued;
28574
+ } finally {
28575
+ sealing.delete(queued);
28576
+ }
28577
+ const sending = flush();
28578
+ if (options.wait) await sending;
28579
+ return "queued";
28580
+ }
28581
+ /** Send one version, read it back, check it opens to what was sealed, and mark it verified. */
28582
+ async function send(version) {
28583
+ if (await deps.api.upload(version.docId, version) === "skipped") return;
28584
+ const ring = keyring();
28585
+ const open = (envelope) => openVersion({
28586
+ keyring: ring,
28587
+ graphId: deps.graphId,
28588
+ docId: version.docId,
28589
+ versionId: version.versionId,
28590
+ envelope
28591
+ });
28592
+ const [sent, stored] = await Promise.all([open(version.envelope), deps.api.get(version.docId, version.versionId).then((got) => open(got.envelope))]);
28593
+ if (JSON.stringify(sent) !== JSON.stringify(stored)) throw new VersionMismatchError("The stored version does not match");
28594
+ await deps.api.verify(version.docId, version.versionId);
28595
+ }
28596
+ /** The same version sealed again under the graph's current epoch, for a server that moved on. */
28597
+ async function resealed(version) {
28598
+ const ring = keyring();
28599
+ const payload = await openVersion({
28600
+ keyring: ring,
28601
+ graphId: deps.graphId,
28602
+ docId: version.docId,
28603
+ versionId: version.versionId,
28604
+ envelope: version.envelope
28605
+ });
28606
+ const sealed = await sealVersion({
28607
+ keyring: ring,
28608
+ graphId: deps.graphId,
28609
+ docId: version.docId,
28610
+ versionId: version.versionId,
28611
+ payload
28612
+ });
28613
+ return {
28614
+ ...version,
28615
+ epochId: sealed.epochId,
28616
+ envelope: sealed.envelope
28617
+ };
28618
+ }
28619
+ function scheduleRetry() {
28620
+ if (retryTimer !== null || disposed) return;
28621
+ retryTimer = setTimer(() => {
28622
+ retryTimer = null;
28623
+ flush();
28624
+ }, retryMs);
28625
+ }
28626
+ /** Send one version, sealing it again once if the server has moved to a new epoch. */
28627
+ async function sendCurrent(version) {
28628
+ try {
28629
+ await send(version);
28630
+ return version;
28631
+ } catch (error) {
28632
+ if (!(error instanceof VersionApiError) || error.code !== "stale_epoch") throw error;
28633
+ const again = await resealed(version);
28634
+ await deps.outbox.put(deps.graphId, again);
28635
+ await send(again);
28636
+ return again;
28637
+ }
28638
+ }
28639
+ /**
28640
+ * What a failed send means: `retry` keeps the version and tries again later (no connection,
28641
+ * or a key this device has not collected yet); `drop` removes it, because sending it again
28642
+ * will not change the answer.
28643
+ */
28644
+ function onSendFailure(error, version) {
28645
+ if (error instanceof VersionApiUnavailableError) return "retry";
28646
+ if (error instanceof VersionApiError && error.code === "future_epoch") return "retry";
28647
+ if (error instanceof VersionApiError) deps.onRefused?.(error, version);
28648
+ return "drop";
28649
+ }
28650
+ async function drain() {
28651
+ for (const queued of await deps.outbox.list(deps.graphId)) {
28652
+ if (disposed) return;
28653
+ try {
28654
+ const sent = await sendCurrent(queued);
28655
+ await deps.outbox.remove(deps.graphId, sent.versionId);
28656
+ } catch (error) {
28657
+ if (onSendFailure(error, queued) === "retry") {
28658
+ scheduleRetry();
28659
+ return;
28660
+ }
28661
+ await deps.outbox.remove(deps.graphId, queued.versionId);
28662
+ }
28663
+ }
28664
+ }
28665
+ function flush() {
28666
+ if (disposed) return Promise.resolve();
28667
+ if (sealing.size > 0) return Promise.allSettled([...sealing]).then(() => flush());
28668
+ if (flushing) {
28669
+ flushAgain = true;
28670
+ return flushing;
28671
+ }
28672
+ flushing = (async () => {
28673
+ do {
28674
+ flushAgain = false;
28675
+ await drain().catch(() => scheduleRetry());
28676
+ } while (flushAgain && !disposed);
28677
+ })().finally(() => {
28678
+ flushing = null;
28679
+ });
28680
+ return flushing;
28681
+ }
28682
+ function onIdle(docId) {
28683
+ const state = stateOf(docId);
28684
+ state.timer = null;
28685
+ if (!state.dirty || disposed) return;
28686
+ const wait = state.lastRecordedAt + gapMs - now();
28687
+ if (wait > 0) {
28688
+ state.timer = setTimer(() => onIdle(docId), wait);
28689
+ return;
28690
+ }
28691
+ keepIdle(docId, state);
28692
+ }
28693
+ function keepIdle(docId, state) {
28694
+ state.dirty = false;
28695
+ record(docId, "idle").catch(() => void 0);
28696
+ }
28697
+ function settle(docId) {
28698
+ if (disposed) return;
28699
+ for (const [id, state] of docId === void 0 ? documents : [[docId, documents.get(docId)]]) {
28700
+ if (!state?.dirty) continue;
28701
+ if (state.timer !== null) clearTimer(state.timer);
28702
+ state.timer = null;
28703
+ keepIdle(id, state);
28704
+ }
28705
+ }
28706
+ return {
28707
+ record,
28708
+ noteLocalEdit(docId) {
28709
+ if (disposed) return;
28710
+ const state = stateOf(docId);
28711
+ state.dirty = true;
28712
+ if (state.timer !== null) clearTimer(state.timer);
28713
+ state.timer = setTimer(() => onIdle(docId), idleMs);
28714
+ },
28715
+ settle,
28716
+ flush,
28717
+ async forget(docId) {
28718
+ const state = documents.get(docId);
28719
+ if (state) {
28720
+ if (state.timer !== null) clearTimer(state.timer);
28721
+ documents.delete(docId);
28722
+ }
28723
+ await flushing;
28724
+ for (const version of await deps.outbox.list(deps.graphId)) if (version.docId === docId) await deps.outbox.remove(deps.graphId, version.versionId);
28725
+ },
28726
+ dispose() {
28727
+ disposed = true;
28728
+ for (const state of documents.values()) if (state.timer !== null) clearTimer(state.timer);
28729
+ if (retryTimer !== null) clearTimer(retryTimer);
28730
+ documents.clear();
28731
+ }
28732
+ };
28733
+ }
28734
+ // ../client/src/lib/sync/version-history/graph-versions.ts
28735
+ function openGraphVersions(deps) {
28736
+ const api = createVersionApi({
28737
+ graphId: deps.graphId,
28738
+ baseUrl: deps.baseUrl,
28739
+ syncToken: deps.syncToken,
28740
+ fetch: deps.fetch
28741
+ });
28742
+ const recorder = createVersionRecorder({
28743
+ graphId: deps.graphId,
28744
+ keyring: deps.keyring,
28745
+ api,
28746
+ outbox: deps.outbox,
28747
+ source: { read: (docId) => deps.store.versionSnapshot(docId) },
28748
+ onRefused: deps.onRefused,
28749
+ idleMs: deps.idleMs
28750
+ });
28751
+ const registry = deps.graph.registry();
28752
+ const unobserve = deps.graph.onDocUpdate((docId, local) => {
28753
+ if (local && registry.has(docId)) recorder.noteLocalEdit(docId);
28754
+ });
28755
+ recorder.flush();
28756
+ return {
28757
+ api,
28758
+ recorder,
28759
+ history: createVersionHistory({
28760
+ graphId: deps.graphId,
28761
+ keyring: deps.keyring,
28762
+ api,
28763
+ recorder,
28764
+ store: deps.store,
28765
+ assetName: deps.assetName
28766
+ }),
28767
+ dispose() {
28768
+ recorder.settle();
28769
+ unobserve();
28770
+ recorder.dispose();
28771
+ }
28772
+ };
28773
+ }
28774
+ // ../client/src/lib/sync/version-history/version-outbox.ts
28775
+ /** For the Headless Client and tests: kept for the life of the process. */
28776
+ function memoryVersionOutbox() {
28777
+ const rows = /* @__PURE__ */ new Map();
28778
+ return {
28779
+ async put(graphId, version) {
28780
+ rows.set(`${graphId}/${version.versionId}`, {
28781
+ graphId,
28782
+ version
28783
+ });
28784
+ },
28785
+ async list(graphId) {
28786
+ return [...rows.values()].filter((row) => row.graphId === graphId).map((row) => row.version).sort((a, b) => a.queuedAt - b.queuedAt);
28787
+ },
28788
+ async remove(graphId, versionId) {
28789
+ rows.delete(`${graphId}/${versionId}`);
28790
+ }
28791
+ };
28792
+ }
28793
+ // src/headless-versions.ts
28794
+ function headlessVersions(versions, documentIdOf) {
28795
+ const make = (versioned) => ({
28796
+ async beforeAgentWrite(concept) {
28797
+ const docId = documentIdOf(concept);
28798
+ if (!docId || versioned.has(docId)) return;
28799
+ versioned.add(docId);
28800
+ await versions.recorder.record(docId, "before_agent_write", { wait: true });
28801
+ },
28802
+ async list(concept) {
28803
+ const docId = documentIdOf(concept);
28804
+ return docId ? versions.history.list(docId) : null;
28805
+ },
28806
+ async read(concept, versionId) {
28807
+ const docId = documentIdOf(concept);
28808
+ return docId ? versions.history.read(docId, versionId) : null;
28809
+ },
28810
+ flush: () => versions.recorder.flush(),
28811
+ forSession: () => make(/* @__PURE__ */ new Set())
28812
+ });
28813
+ return make(/* @__PURE__ */ new Set());
28814
+ }
27833
28815
  // ../client/src/lib/sync/write-refusal.ts
27834
28816
  var AGENT_REASONS = {
27835
28817
  entitlement_inactive: "the graph owner's plan does not allow changes at the moment (a lapsed, unpaid or unconfirmed plan)",
@@ -27957,6 +28939,7 @@ function assembleHeadlessGraph(parts) {
27957
28939
  store: parts.store,
27958
28940
  index,
27959
28941
  assets: parts.assets,
28942
+ versions: parts.versions,
27960
28943
  backend: parts.backend,
27961
28944
  publishing: parts.publishing,
27962
28945
  themes: parts.themes,
@@ -28004,7 +28987,11 @@ async function openHeadlessGraph(deps) {
28004
28987
  publishName: deps.publishName
28005
28988
  });
28006
28989
  const connection = followConnection(sync, { onChange: deps.onConnectionChange });
28007
- const store = createServerDocumentStore(sync, { readyTimeoutMs: deps.readyTimeoutMs });
28990
+ let graphVersions;
28991
+ const store = createServerDocumentStore(sync, {
28992
+ readyTimeoutMs: deps.readyTimeoutMs,
28993
+ recordVersion: (docId, reason, snapshot) => void graphVersions?.recorder.record(docId, reason, { snapshot }).catch((error) => deps.onError?.(error instanceof Error ? error : new Error(String(error))))
28994
+ });
28008
28995
  try {
28009
28996
  await store.scan();
28010
28997
  const index = createRemoteGraphIndex(store, inlineTransport(indexHost ?? memoryDbHost()), { graphId: deps.graphId });
@@ -28090,9 +29077,22 @@ async function openHeadlessGraph(deps) {
28090
29077
  uploaded: /* @__PURE__ */ new Set()
28091
29078
  };
28092
29079
  }
29080
+ if (deps.assets && !("store" in deps.assets)) graphVersions = openGraphVersions({
29081
+ graphId: deps.graphId,
29082
+ graph: sync,
29083
+ keyring: deps.keyring,
29084
+ baseUrl: deps.assets.baseUrl,
29085
+ syncToken: deps.token,
29086
+ outbox: memoryVersionOutbox(),
29087
+ store,
29088
+ fetch: deps.assets.fetch,
29089
+ onRefused: (error) => deps.onError?.(/* @__PURE__ */ new Error(`The Sync Server refused a document version: ${error.message}`))
29090
+ });
29091
+ const versions = graphVersions ? headlessVersions(graphVersions, (concept) => store.documentIdOf(concept)) : void 0;
28093
29092
  return assembleHeadlessGraph({
28094
29093
  graphId: deps.graphId,
28095
29094
  name: sync.getMeta().name ?? deps.graphId,
29095
+ versions,
28096
29096
  accessLoss: () => sync.accessLoss(),
28097
29097
  connection: () => connection.current(),
28098
29098
  store: documents,
@@ -28126,6 +29126,7 @@ async function openHeadlessGraph(deps) {
28126
29126
  persistBackend: deps.persistDir ? () => persistLocalCache(deps.persistDir, cacheName) : void 0,
28127
29127
  onChange: (schedule) => sync.onDocUpdate(schedule),
28128
29128
  async settle(schedulePersist) {
29129
+ await versions?.flush();
28129
29130
  await sync.flushAll();
28130
29131
  const result = await sync.awaitAcked({ stallMs: 1e4 });
28131
29132
  schedulePersist();
@@ -28143,6 +29144,7 @@ async function openHeadlessGraph(deps) {
28143
29144
  };
28144
29145
  },
28145
29146
  async disposeBackend() {
29147
+ graphVersions?.dispose();
28146
29148
  follower.dispose();
28147
29149
  await store.dispose();
28148
29150
  cache.dispose();