@milaboratories/pl-middle-layer 1.68.2 → 1.69.0

package/src/middle_layer/sharing_list.ts

@@ -15,11 +15,14 @@ import type {
   EnvelopeAcceptance,
   EnvelopeData,
   EnvelopeMode,
+  EnvelopePayloadKind,
   ShareId,
 } from "../model/sharing_model";
 import {
   AcceptanceFieldPrefix,
   asShareId,
+  envelopeProjectMap,
+  normalizeEnvelopeData,
   SharedEnvelopeResourceType,
   SharingOutboxResourceType,
   SharingStateResourceType,
@@ -32,19 +35,28 @@ export interface OutgoingShare {
   expiresAt?: number; // EnvelopeData.expiresAt; null maps to undefined = never expires
   mode: EnvelopeMode;
   title: string; // display name shown to recipients; defaults to the first project's name
+  /** What the share carries — a pack of projects, or one template document. */
+  payloadKind: EnvelopePayloadKind;
   /** One entry per project in the pack, so the change UI can offer a per-project decision.
    *  `projectId` is the donor's source project id; `updatedAt` is when this project's
-   *  snapshot was last (re)taken. */
+   *  snapshot was last (re)taken. Empty for a template share. */
   projects: { projectId: ProjectId; label: string; updatedAt: number }[];
+  /** The shared template, for a template share; absent for a project share. */
+  template?: { label: string; blockCount: number };
   /** Full recipient logins, from `ListGrants` on the envelope; `["*"]` for everyone-shares. */
   recipients: string[];
+  /** Whether {@link responses} can ever be populated for this share. A template share is granted
+   *  read-only, so no recipient can record a reply on the envelope and the donor never learns who
+   *  accepted — a view must say so rather than render an empty response list as "nobody yet". */
+  responsesAvailable: boolean;
   /** Per recipient who has responded: their decision and when, from acceptance/{login}. */
   responses: Record<string, { action: "accepted" | "rejected"; timestamp: number }>;
 }
 
-/** Per-project view for the donor's change UI, from {@link EnvelopeData.projects}. */
+/** Per-project view for the donor's change UI, from the envelope's `projects` payload; empty
+ *  for a payload that carries no project. */
 function envelopeProjects(data: EnvelopeData): OutgoingShare["projects"] {
-  return Object.values(data.projects).map((p) => ({
+  return Object.values(envelopeProjectMap(data)).map((p) => ({
     projectId: p.source,
     label: p.label,
     updatedAt: p.updatedAt,
@@ -57,6 +69,9 @@ export interface PendingShare {
   sender: string; // EnvelopeData.sender, display only
   title: string; // display name shown to recipients; defaults to the first project's name
   mode: EnvelopeMode; // v1 renders only "copy" entries
+  /** What the offer carries, so the recipient is told what they are being offered — projects to
+   *  copy, or a template for their own shelf. */
+  payloadKind: EnvelopePayloadKind;
   grantedAt: number;
 }
 
@@ -108,8 +123,8 @@ export function createOutgoingSharesComputable(
         if (envelope === undefined) continue;
         if (!resourceTypesEqual(envelope.resourceType, SharedEnvelopeResourceType)) continue;
 
-        const data = envelope.getDataAsJson<EnvelopeData>();
-        if (data === undefined) continue;
+        const data = normalizeEnvelopeData(envelope.getDataAsJson<unknown>());
+        if (data === undefined) continue; // unknown version or payload kind — not ours to show
 
         const responses: OutgoingShare["responses"] = {};
         for (const f of envelope.listDynamicFields()) {
@@ -127,7 +142,17 @@ export function createOutgoingSharesComputable(
           ...(data.expiresAt !== null ? { expiresAt: data.expiresAt } : {}),
           mode: data.mode,
           title: data.title,
+          payloadKind: data.payload.kind,
           projects: envelopeProjects(data),
+          ...(data.payload.kind === "template"
+            ? {
+                template: {
+                  label: data.payload.label,
+                  blockCount: data.payload.document.blocks.length,
+                },
+              }
+            : {}),
+          responsesAvailable: data.payload.kind !== "template",
           responses,
           envelopeRid: envelope.id,
         });
@@ -255,7 +280,9 @@ export function createLiveEnvelopesComputable(
     for (const envelope of roots) {
       if (envelope === undefined) continue;
       if (!resourceTypesEqual(envelope.resourceType, SharedEnvelopeResourceType)) continue;
-      const data = envelope.getDataAsJson<EnvelopeData>();
+      const data = normalizeEnvelopeData(envelope.getDataAsJson<unknown>());
+      // Same recognise-or-hide rule as the pending view, and for the same envelope: hiding an
+      // offer while accept could still resolve it would only move the problem.
       if (data === undefined) continue;
       result.push({ rid: envelope.id, data });
     }
@@ -292,7 +319,9 @@ export function createPendingSharesComputable(
     for (const envelope of roots) {
       if (envelope === undefined) continue;
       if (!resourceTypesEqual(envelope.resourceType, SharedEnvelopeResourceType)) continue;
-      const data = envelope.getDataAsJson<EnvelopeData>();
+      const data = normalizeEnvelopeData(envelope.getDataAsJson<unknown>());
+      // An envelope whose schemaVersion or payload kind this build does not know is hidden, not
+      // offered: there is nothing useful to do with a share we cannot read.
       if (data === undefined) continue;
       if (handled.has(data.shareId)) continue; // already accepted or rejected
       if (currentUserLogin !== null && data.sender === currentUserLogin) continue; // own share
@@ -303,6 +332,7 @@ export function createPendingSharesComputable(
         sender: data.sender,
         title: data.title,
         mode: data.mode,
+        payloadKind: data.payload.kind,
         grantedAt: data.sharedAt,
       });
     }

package/src/middle_layer/template_list.ts

@@ -0,0 +1,177 @@
+import type { PruningFunction } from "@milaboratories/pl-tree";
+import { SynchronizedTreeState } from "@milaboratories/pl-tree";
+import type {
+  Filter,
+  PlClient,
+  PlTransaction,
+  ResourceType,
+  SignedResourceId,
+} from "@milaboratories/pl-client";
+import {
+  field,
+  isNullSignedResourceId,
+  resourceIdToString,
+  resourceTypesEqual,
+  treeFilter,
+} from "@milaboratories/pl-client";
+import type { TreeAndComputableU } from "./types";
+import { Computable } from "@milaboratories/computable";
+import type { MiddleLayerEnvironment } from "./middle_layer";
+import { notEmpty } from "@milaboratories/ts-helpers";
+import type { Branded, ProjectTemplateV1 } from "@milaboratories/pl-model-common";
+import type { TemplateExportProblem } from "../model/template_export";
+import type { TemplateShareProblem } from "../model/template_share";
+import type { ShareId } from "../model/sharing_model";
+import type { AppliedEntry, TemplateApplyProblem } from "../model/template_apply";
+import type { ProjectId } from "../model/project_model";
+
+export const TemplatesField = "templates";
+export const TemplatesResourceType: ResourceType = { name: "Templates", version: "1" };
+export const TemplateResourceType: ResourceType = { name: "UserTemplate", version: "1" };
+
+/** Mutable: the only part of a stored template a rename may touch. */
+export const TemplateLabelKey = "TemplateLabel";
+export const TemplateCreatedTimestamp = "TemplateCreated";
+
+/**
+ * Unique template identifier in middle layer, the stringified signed resource id of the
+ * `UserTemplate`. Branded so it cannot be confused with a {@link ProjectId} — both are
+ * stringified resource ids and every template method takes one of them.
+ */
+export type TemplateId = Branded<string, "TemplateId">;
+
+/**
+ * Immutable `data` on a UserTemplate: the document plus what was true when it was taken.
+ *
+ * The document lives here and never in KV: KV is listed and fully re-read on every poll,
+ * while resource data syncs incrementally, and a template document is a multi-kilobyte
+ * value that never changes.
+ */
+export interface StoredTemplateData {
+  schemaVersion: 1;
+  document: ProjectTemplateV1;
+  /** Provenance, display only; absent for a template that arrived as a share. */
+  sourceProjectLabel?: string;
+  /** Login of the sender, when it arrived as a share. */
+  sender?: string;
+}
+
+/** Decodes the immutable `data` blob of a `UserTemplate` read through a transaction. The
+ *  single raw-decode site; the tree side reads the same JSON with `getDataAsJson`. */
+export function decodeStoredTemplateData(data: Uint8Array): StoredTemplateData {
+  return JSON.parse(Buffer.from(data).toString("utf-8")) as StoredTemplateData;
+}
+
+/** One template as the template list surfaces it. */
+export interface TemplateListEntry {
+  /** Unique template identifier in middle layer. Use to operate with the given template. */
+  id: TemplateId;
+  /** The mutable label, the only part a rename changes. */
+  label: string;
+  created: Date;
+  /** Number of blocks the stored document lists — derived, not stored. */
+  blockCount: number;
+  sourceProjectLabel?: string;
+  sender?: string;
+}
+
+/** What saving a project as a template yields: the stored template, or every block in the way. */
+export type SaveProjectAsTemplateOutcome =
+  | { readonly ok: true; readonly templateId: TemplateId }
+  | { readonly ok: false; readonly problems: readonly TemplateExportProblem[] };
+
+/** What sharing a stored template yields: the share's logical id, or every entry in the way. */
+export type ShareTemplateOutcome =
+  | { readonly ok: true; readonly shareId: ShareId }
+  | { readonly ok: false; readonly problems: readonly TemplateShareProblem[] };
+
+/**
+ * What applying a stored template yields.
+ *
+ * `ok: false` carries no project id because no project was created: nothing is written
+ * until every entry has an installable block.
+ */
+export type CreateProjectFromTemplateOutcome =
+  | {
+      readonly ok: true;
+      readonly projectId: ProjectId;
+      readonly added: readonly AppliedEntry[];
+    }
+  | { readonly ok: false; readonly problems: readonly TemplateApplyProblem[] };
+
+/**
+ * Resolves the templates-list resource on the transaction's client root, lazily creating (and
+ * locking) an empty one when the {@link TemplatesField} is not yet populated. Returns its signed
+ * id. Used when writing into a root that may have no templates list yet, e.g. a template landing
+ * in a recipient's root.
+ */
+export async function ensureTemplateListRid(tx: PlTransaction): Promise<SignedResourceId> {
+  const templatesField = field(tx.clientRoot, TemplatesField);
+  tx.createField(templatesField, "Dynamic");
+  const fData = await tx.getField(templatesField);
+  if (isNullSignedResourceId(fData.value)) {
+    const ref = tx.createEphemeral(TemplatesResourceType);
+    tx.lock(ref);
+    tx.setField(templatesField, ref);
+    return await ref.globalId;
+  }
+  return fData.value;
+}
+
+export const TemplatesListTreePruningFunction: PruningFunction = (resource) => {
+  if (!resourceTypesEqual(resource.type, TemplatesResourceType)) return [];
+  return resource.fields;
+};
+
+export const templatesListFieldFilter: Filter = treeFilter.resourceTypeEq(
+  TemplatesResourceType.name,
+);
+
+export async function createTemplateList(
+  pl: PlClient,
+  rid: SignedResourceId,
+  env: MiddleLayerEnvironment,
+): Promise<TreeAndComputableU<TemplateListEntry[]>> {
+  const tree = await SynchronizedTreeState.init(
+    pl,
+    rid,
+    {
+      ...env.ops.defaultTreeOptions,
+      pruning: TemplatesListTreePruningFunction,
+      fieldFilter: templatesListFieldFilter,
+    },
+    env.logger,
+  );
+
+  const c = Computable.make((ctx) => {
+    const node = ctx.accessor(tree.entry()).node();
+    if (node === undefined) return undefined;
+    const result: TemplateListEntry[] = [];
+
+    // Templates list resource keeps templates assigned to fields. Each field name is a UUID
+    for (const field of node.listDynamicFields()) {
+      const tpl = node.traverse(field);
+      if (tpl === undefined) continue;
+      const data = tpl.getDataAsJson<StoredTemplateData>();
+      // A template whose data has not synced yet is not an entry with unknown content —
+      // it is an entry we cannot describe at all, so it stays out of the list until it has.
+      if (data === undefined) continue;
+      const label = notEmpty(tpl.getKeyValueAsJson<string>(TemplateLabelKey));
+      const created = notEmpty(tpl.getKeyValueAsJson<number>(TemplateCreatedTimestamp));
+      result.push({
+        id: resourceIdToString(tpl.id) as TemplateId,
+        label,
+        created: new Date(created),
+        blockCount: data.document.blocks.length,
+        ...(data.sourceProjectLabel !== undefined
+          ? { sourceProjectLabel: data.sourceProjectLabel }
+          : {}),
+        ...(data.sender !== undefined ? { sender: data.sender } : {}),
+      });
+    }
+    result.sort((a, b) => b.created.valueOf() - a.created.valueOf());
+    return result;
+  }).withStableType();
+
+  return { computable: c, tree };
+}

package/src/middle_layer/templates.test.ts

@@ -0,0 +1,301 @@
+import { expect, test } from "vitest";
+import * as tp from "node:timers/promises";
+import type { ResourceRef, SignedResourceId } from "@milaboratories/pl-client";
+import { resourceIdToString } from "@milaboratories/pl-client";
+import type {
+  BlockKindSelectorReference,
+  BlockPackLocationReference,
+  ProjectTemplateV1,
+  ProjectTemplateV1Entry,
+} from "@milaboratories/pl-model-common";
+import { PROJECT_TEMPLATE_SCHEMA_V1 } from "@milaboratories/pl-model-common";
+import type { BlockPackSpec } from "@milaboratories/pl-model-middle-layer";
+import type { BlockPackProvider } from "../model/template_resolve";
+import { withMl } from "../test/with_ml";
+import { createTemplate } from "../mutator/template";
+import type { MiddleLayer } from "./middle_layer";
+import type { StoredTemplateData, TemplateId, TemplateListEntry } from "./template_list";
+import { ensureTemplateListRid } from "./template_list";
+
+/**
+ * The stored-template entity against a live backend: rename, apply, share, accept.
+ *
+ * Every test here stores its template directly through the mutator rather than by saving a
+ * project, so the document under test is the one the test wrote — a `file:` entry, an entry
+ * nothing can resolve — none of which a real project would produce. What a real project
+ * produces is covered by the round trip in `drivers-ml-blocks-integration`, which has block
+ * packs on disk to build one from.
+ *
+ * Needs a backend, like every `withMl` test in this package, and no gate: `PL_ADDRESS` is
+ * either configured or the client fails to connect.
+ */
+
+const KIND = "@platforma-open/milaboratories.demo.kind@^1.0.0" as BlockKindSelectorReference;
+
+/** A block installed from a folder on the author's own machine. */
+const LOCAL_FOLDER = "file:///Users/dev/blocks/demo/block" as BlockPackLocationReference;
+
+/** A legacy registry block, which predates kinds — so it cannot be written to a template. */
+const KindlessBlock: BlockPackSpec = {
+  type: "from-registry-v1",
+  registryUrl: "https://block.registry.platforma.bio/releases",
+  id: { organization: "milaboratory", name: "enter-numbers", version: "1.1.1" },
+};
+
+test("a rename changes the label and leaves the stored document byte-identical", async () => {
+  await withMl(async (ml) => {
+    const document = documentOf(entry("a"), entry("b"));
+    const stored = await storeTemplate(ml, "First name", {
+      schemaVersion: 1,
+      document,
+      sourceProjectLabel: "Source project",
+    });
+    const dataBefore = await rawTemplateData(ml, stored.rid);
+
+    await ml.renameTemplate(stored.id, "Second name");
+
+    // The label is the only mutable part: the document rides in the immutable `data` blob,
+    // which has no setter — improving a template means saving a new one.
+    expect(await rawTemplateData(ml, stored.rid)).toStrictEqual(dataBefore);
+    expect((await ml.getTemplateData(stored.id)).document).toStrictEqual(document);
+
+    const list = await awaitTemplateList(ml, (l) => l.some((t) => t.label === "Second name"));
+    expect(list).toHaveLength(1);
+    expect(list[0]).toMatchObject({
+      id: stored.id,
+      label: "Second name",
+      blockCount: 2,
+      sourceProjectLabel: "Source project",
+    });
+  });
+});
+
+test("an entry nothing can resolve creates no project, and every entry is reported", async () => {
+  await withMl(async (ml) => {
+    const stored = await storeTemplate(ml, "Nothing implements these", {
+      schemaVersion: 1,
+      document: documentOf(entry("a"), entry("b")),
+    });
+
+    const outcome = await ml.createProjectFromTemplate(
+      stored.id,
+      "From a template",
+      resolvesNothing(),
+    );
+
+    if (outcome.ok) throw new Error("a template nothing can resolve must not apply");
+    // Resolution runs before the project exists, which is what makes this a statement about
+    // the template rather than about a half-built project.
+    expect(outcome.problems.map((p) => p.entryId)).toStrictEqual(["a", "b"]);
+    expect(await ml.projectList.awaitStableValue()).toStrictEqual([]);
+  });
+});
+
+test("a template holding a block from a folder on this machine is refused rather than shared", async () => {
+  await withMl(async (ml) => {
+    const stored = await storeTemplate(ml, "Built here", {
+      schemaVersion: 1,
+      document: documentOf(entry("a"), entry("b", LOCAL_FOLDER)),
+    });
+
+    // Asked of a template that is merely being displayed, so the refusal can be stated on the
+    // template itself instead of only once the user has tried to send it.
+    expect((await ml.checkTemplateShareable(stored.id)).map((p) => p.entryId)).toStrictEqual(["b"]);
+
+    const outcome = await ml.shareTemplate(stored.id, {
+      recipients: ["colleague"],
+      title: "Built here",
+    });
+
+    if (outcome.ok) throw new Error("a template with a file: entry must not be shareable");
+    expect(outcome.problems.map((p) => p.entryId)).toStrictEqual(["b"]);
+    // Refused before anything was written: no envelope, so nothing to revoke.
+    expect((await ml.outgoingShares.getValue()) ?? []).toStrictEqual([]);
+  });
+});
+
+test("a project holding a block that cannot be written out produces no template", async () => {
+  await withMl(async (ml) => {
+    const projectId = await ml.createProject({ label: "Two legacy blocks" });
+    await ml.openProject(projectId);
+    const project = ml.getOpenedProject(projectId);
+
+    const first = await project.addBlock("Block 1", KindlessBlock);
+    const second = await project.addBlock("Block 2", KindlessBlock);
+
+    const outcome = await ml.saveProjectAsTemplate(projectId);
+
+    if (outcome.ok) throw new Error("a project with an unexportable block must store no template");
+    // Every offending block at once, not the first one: fixing an unexportable project takes
+    // one pass, not one pass per block.
+    expect(outcome.problems.map((p) => p.blockId).sort()).toStrictEqual([first, second].sort());
+    expect(await ml.templateList.awaitStableValue()).toStrictEqual([]);
+  });
+});
+
+test("an accepted template share lands on the acceptor's shelf and builds nothing", async () => {
+  await withMl(async (ml) => {
+    const stored = await storeTemplate(ml, "A pipeline", {
+      schemaVersion: 1,
+      document: documentOf(entry("a")),
+      sourceProjectLabel: "Source project",
+    });
+
+    const shared = await ml.shareTemplate(stored.id, { everyone: true, title: "A pipeline" });
+    if (!shared.ok) throw new Error(`share refused: ${JSON.stringify(shared.problems)}`);
+
+    const outcome = await ml.acceptShare([shared.shareId]);
+
+    expect(outcome.failed).toStrictEqual([]);
+    expect(outcome.acceptedTemplates).toHaveLength(1);
+    // Nothing is built until the recipient applies it — which is what makes an all-or-nothing
+    // apply survivable for them: there is always something left to retry from.
+    expect(outcome.accepted).toStrictEqual([]);
+    expect(await ml.projectList.awaitStableValue()).toStrictEqual([]);
+
+    const list = await awaitTemplateList(ml, (l) => l.length === 2);
+    const accepted = list.find((t) => t.id === outcome.acceptedTemplates[0])!;
+    expect(accepted.label).toBe("A pipeline");
+    // Who sent it, kept as the accepted template's provenance; the donor's own source project
+    // is not part of the payload and does not travel.
+    expect(accepted.sender).toBe(ml.currentUserLogin ?? "");
+    expect(accepted.sourceProjectLabel).toBeUndefined();
+  });
+});
+
+test("a changed template share keeps its id, and whoever already responded is not re-prompted", async () => {
+  await withMl(async (ml) => {
+    const first = await storeTemplate(ml, "First", {
+      schemaVersion: 1,
+      document: documentOf(entry("a")),
+    });
+    const second = await storeTemplate(ml, "Second", {
+      schemaVersion: 1,
+      document: documentOf(entry("a"), entry("b")),
+    });
+
+    const shared = await ml.shareTemplate(first.id, { everyone: true, title: "First" });
+    if (!shared.ok) throw new Error(`share refused: ${JSON.stringify(shared.problems)}`);
+
+    // Someone responds to the share, which is what the replace below must not undo.
+    const accept = await ml.acceptShare([shared.shareId]);
+    expect(accept.acceptedTemplates).toHaveLength(1);
+
+    // A stored template never changes, so an improved one is a different template — the
+    // replace names it rather than re-reading the one the share started from.
+    await ml.changeShare(shared.shareId, { templateId: second.id, title: "Second" });
+
+    const outgoing = (await ml.outgoingShares.getValue()) ?? [];
+    expect(outgoing.map((s) => s.shareId)).toStrictEqual([shared.shareId]);
+    expect(outgoing[0]).toMatchObject({
+      payloadKind: "template",
+      title: "Second",
+      template: { label: "Second", blockCount: 2 },
+      // A template share is granted read-only, so no recipient can ever write a reply on the
+      // envelope — a view has to say that rather than render an empty list as "nobody yet".
+      responsesAvailable: false,
+    });
+    expect(outgoing[0].projects).toStrictEqual([]);
+
+    // The decision the accept recorded is keyed on the shareId, which the change preserved, so
+    // the replaced share is not offered again. A replace that minted a new id would show up
+    // here as a fresh offer.
+    const pending = await settledPendingShareIds(ml);
+    expect(pending).not.toContain(shared.shareId);
+  });
+});
+
+//
+// Internals
+//
+
+const entry = (id: string, location?: BlockPackLocationReference): ProjectTemplateV1Entry => ({
+  id,
+  kind: KIND,
+  params: {},
+  ...(location !== undefined ? { location } : {}),
+});
+
+const documentOf = (...blocks: ProjectTemplateV1Entry[]): ProjectTemplateV1 => ({
+  schema: PROJECT_TEMPLATE_SCHEMA_V1,
+  blocks,
+});
+
+/** A stored template, plus the resource id needed to read its raw `data` blob back. */
+type StoredTemplate = { id: TemplateId; rid: SignedResourceId };
+
+/**
+ * Stores one template through the mutator, on the same templates list the middle layer reads.
+ *
+ * The middle layer has no way to store an arbitrary document — it only saves a project — so a
+ * test that needs a specific document writes it here, exactly as `saveProjectAsTemplate` and
+ * the accept path do.
+ */
+async function storeTemplate(
+  ml: MiddleLayer,
+  label: string,
+  data: StoredTemplateData,
+): Promise<StoredTemplate> {
+  let tpl: ResourceRef;
+  await ml.pl.withWriteTx("TestStoreTemplate", async (tx) => {
+    const listRid = await ensureTemplateListRid(tx);
+    tpl = createTemplate(tx, listRid, label, data);
+    await tx.commit();
+  });
+  const rid = await tpl!.globalId;
+  return { id: resourceIdToString(rid) as TemplateId, rid };
+}
+
+/** The template's immutable `data` blob, as bytes — the form a rename must not touch. */
+async function rawTemplateData(ml: MiddleLayer, rid: SignedResourceId): Promise<Buffer> {
+  return await ml.pl.withReadTx("TestReadTemplateData", async (tx) => {
+    const rd = await tx.getResourceData(rid, false);
+    if (rd.data === undefined) throw new Error("template carries no document");
+    return Buffer.from(rd.data);
+  });
+}
+
+/**
+ * The template list once it satisfies `predicate`.
+ *
+ * A template written by the mutator lands in the list through the tree's own poll, with no
+ * refresh to await, so a test that stored one waits for it rather than reading once.
+ */
+async function awaitTemplateList(
+  ml: MiddleLayer,
+  predicate: (list: TemplateListEntry[]) => boolean,
+  timeoutMs = 15_000,
+): Promise<TemplateListEntry[]> {
+  const abortSignal = AbortSignal.timeout(timeoutMs);
+  while (true) {
+    const list = await ml.templateList.getValue();
+    if (list !== undefined && predicate(list)) return list;
+    await ml.templateList.awaitChange(abortSignal);
+  }
+}
+
+/**
+ * The shareIds currently offered to this user, read after discovery has had a poll to run.
+ *
+ * Discovery of a just-granted envelope is a poll behind, so reading the view once would say
+ * "not offered" about a share that simply had not been seen yet.
+ */
+async function settledPendingShareIds(ml: MiddleLayer): Promise<string[]> {
+  await tp.setTimeout(2_000);
+  return ((await ml.pendingShares.getValue()) ?? []).map((s) => s.shareId);
+}
+
+/**
+ * A provider that finds nothing, for a document whose entries resolve through their kind.
+ *
+ * `no-implementation` rather than a thrown error: an entry whose kind exists but which
+ * nothing implements is the reachable case, and it is a problem about that entry rather
+ * than a failure of the apply.
+ */
+function resolvesNothing(): BlockPackProvider {
+  return {
+    byKind: () => Promise.resolve({ ok: false, reason: "no-implementation" }),
+    byExactVersion: () => Promise.resolve({ ok: false, reason: "no-such-block-version" }),
+    byLocation: () => Promise.resolve({ ok: false, reason: "not-found" }),
+  };
+}

package/src/model/index.ts

@@ -35,3 +35,17 @@ export {
   type TemplateApplyProblem,
   type TemplateApplyReport,
 } from "./template_apply";
+
+// The template export path. A caller renders a stored template back to a file, and reports
+// every block that stood in the way of storing one, so the outcome type and the stringifier
+// are as public as the `MiddleLayer.saveProjectAsTemplate` that produces them.
+export {
+  stringifyProjectTemplateV1,
+  locationOf,
+  type ProjectTemplateExportOutcome,
+} from "./template_serializer";
+export type { TemplateExportProblem } from "./template_export";
+
+// The template share path. Whether a template may be shared at all is a question a UI asks about
+// a template it is merely displaying, so the check and its problem type are public.
+export { unshareableTemplateEntries, type TemplateShareProblem } from "./template_share";