@milaboratories/pl-middle-layer 1.71.15 → 1.72.0

package/dist/model/sharing_model.d.ts

@@ -1,8 +1,9 @@
-import { Branded, ProjectId, ProjectTemplateV1 } from "@milaboratories/pl-model-common";
+import { FolderId } from "@milaboratories/pl-model-middle-layer";
+import { Branded, ProjectId, ProjectTemplateV1, TemplateId } from "@milaboratories/pl-model-common";
 import { ResourceType, Role } from "@milaboratories/pl-client";
 //#region src/model/sharing_model.d.ts
 /**
- * Logical identity of a share, stable across replaces. A donor-generated UUID string,
+ * Identity of one share. A donor-generated UUID string,
  * branded so it cannot be silently confused with a project id, a login, or a raw field
  * name. Minted once with {@link newShareId}; every other site receives it (from decoded
  * {@link EnvelopeData} or by parsing a `decision/{shareId}` field name) and threads it
@@ -16,18 +17,17 @@ export declare function newShareId(): ShareId;
 export declare function asShareId(id: string): ShareId;
 /** Field on the donor's clientRoot holding the {@link SharingOutboxResourceType} resource. */
 export declare const SharingOutboxField = "sharingOutbox";
-/** Field on the acceptor's clientRoot holding the {@link SharingStateResourceType} resource. */
+/** Field on the recipient's clientRoot holding the {@link SharingStateResourceType} resource. */
 export declare const SharingStateField = "sharingState";
 export declare const SharingOutboxResourceType: ResourceType;
 export declare const SharedEnvelopeResourceType: ResourceType;
 export declare const SharingStateResourceType: ResourceType;
 export type EnvelopeMode = "copy" | "read-only" | "collaboration";
-/** Per-project decision on change, matching the UI labels: re-snapshot the live source ("update"),
- *  carry the existing snapshot ("keep"), or drop the project from the pack ("remove"). */
-export type ProjectChangeAction = "keep" | "update" | "remove";
 /** Key of the per-project envelope maps: a uuid minted per snapshot to name the `project/{uuid}`
  *  field. Distinct from {@link ProjectId} — re-snapshotting one source yields a new uuid each time. */
 export type ProjectFieldUuid = Branded<string, "ProjectFieldUuid">;
+/** Mints a fresh {@link ProjectFieldUuid} for one snapshot. */
+export declare function newProjectFieldUuid(): ProjectFieldUuid;
 /**
  * Whether a role may make a resource public (grant to everyone): true for controller,
  * admin; false for workflow and unspecified. The middle layer carries no policy
@@ -51,6 +51,40 @@ export interface EnvelopeProject {
   label: string;
   source: ProjectId;
   updatedAt: number;
+  /** What the project said about itself when it was snapshotted, carried for the same reason as
+   *  `label`. Absent when it had none, and on envelopes written before it was carried. */
+  description?: string;
+}
+/**
+ * Identifier of a folder inside one envelope.
+ *
+ * Local to the envelope, because the recipient's own folder document mints its own ids and the
+ * donor's mean nothing there. What travels is the shape of the subtree, not its identity.
+ */
+export type EnvelopeFolderId = Branded<string, "EnvelopeFolderId">;
+/** Mints a fresh {@link EnvelopeFolderId} for one folder of the envelope being built. */
+export declare function newEnvelopeFolderId(): EnvelopeFolderId;
+/** One folder of a shared subtree. */
+export interface EnvelopeFolder {
+  name: string;
+  /** Absent for the subtree's root — the folder that was shared. */
+  parent?: EnvelopeFolderId;
+  /** What the donor wrote about the folder. Absent when there is none. */
+  description?: string;
+}
+/** A project of a shared subtree: an {@link EnvelopeProject} placed in the subtree. */
+export interface EnvelopeFolderProject extends EnvelopeProject {
+  folder: EnvelopeFolderId;
+}
+/** A template of a shared subtree. The document rides here whole, exactly as a `template`
+ *  payload carries it — a template is never snapshotted. */
+export interface EnvelopeFolderTemplate {
+  document: ProjectTemplateV1;
+  /** Label to give the template among the recipient's templates. */
+  label: string;
+  /** What the template says about itself. Absent when the donor described it with nothing. */
+  description?: string;
+  folder: EnvelopeFolderId;
 }
 /**
  * What a share carries. The discriminant is what a reader checks before anything else: a
@@ -66,9 +100,30 @@ export type EnvelopePayload = {
 } | {
   kind: "template";
   document: ProjectTemplateV1;
-  /** Label to give the template on the recipient's own shelf. */
+  /** Donor's own id of the shared template; what a prior share of the same template is
+   *  matched on. It names nothing in the recipient's tree, and envelopes written before it
+   *  existed carry none — those match no later share of anything. */
+  source?: TemplateId;
+  /** Label to give the template among the recipient's templates. */
   label: string;
-  /** Donor login, kept on the accepted template as its provenance. */
+  /** What the template says about itself, carried to the recipient's copy. Absent when the
+   *  donor described it with nothing. */
+  description?: string;
+  /** Donor login, kept on each copy of the template as its provenance. */
+  from: string;
+} | {
+  kind: "folder";
+  /** Donor's own id of the shared folder; what a prior share of the same folder is matched
+   *  on. It names nothing in the recipient's tree. */
+  source: FolderId;
+  /** The shared subtree. Exactly one folder has no parent, and that one is its root. */
+  folders: Record<EnvelopeFolderId, EnvelopeFolder>;
+  /** Project snapshots, each tagged with the folder of the subtree holding it. Their
+   *  `project/{uuid}` fields are the same ones a `projects` payload describes. */
+  projects: Record<ProjectFieldUuid, EnvelopeFolderProject>;
+  /** Templates of the subtree, documents and all. Nothing of a template is snapshotted. */
+  templates: EnvelopeFolderTemplate[];
+  /** Donor login, kept on each copied template as its provenance. */
   from: string;
 };
 export type EnvelopePayloadKind = EnvelopePayload["kind"];
@@ -98,27 +153,33 @@ export interface EnvelopeData {
 /** The project map of a projects-payload envelope, or `{}` for any other payload — the one
  *  place a project-shaped reader turns a payload into the map it expects. */
 export declare function envelopeProjectMap(data: EnvelopeData): Record<ProjectFieldUuid, EnvelopeProject>;
-/** Dynamic field on SharingState, one per handled share, keyed by shareId. */
-export declare const decisionField: (shareId: ShareId) => string;
-export interface SharingDecision {
-  decision: "accepted" | "rejected";
-  timestamp: number;
-  envelopeSharedAt: number;
-  acceptedProjects: string[];
-}
-/** Dynamic field on SharedEnvelope, one per recipient who accepted or rejected, keyed
- *  by recipient login. Written by the acceptor in read-write shares only (Copy & Share,
- *  Live collaboration) — the acceptor's writable envelope grant is what permits the
- *  write; read-only shares omit it. The donor reads these from its own outbox to see
- *  who responded and when. Informational, not authoritative (a writable grant holder
- *  could write under another login — same trust assumption as the sender field).
- *  Copied forward when a share is changed. */
-export declare const AcceptanceFieldPrefix = "acceptance/";
-export declare const acceptanceField: (login: string) => string;
-export declare const isAcceptanceField: (name: string) => boolean;
-export declare const acceptanceFieldLogin: (name: string) => string;
-export interface EnvelopeAcceptance {
-  action: "accepted" | "rejected";
+/**
+ * The shared folder itself: the one folder of the subtree that has no parent.
+ *
+ * Derived rather than stored, so it cannot disagree with the folders beside it. `undefined` for
+ * a subtree with no root or more than one, which is an envelope nothing can be reconstructed
+ * from — the copy reports it rather than guessing which folder was meant.
+ */
+export declare function envelopeFolderRoot(folders: Record<EnvelopeFolderId, EnvelopeFolder>): EnvelopeFolderId | undefined;
+/**
+ * Dynamic field on SharingState, one per share this user has hidden, keyed by shareId.
+ *
+ * Hiding is private to the recipient and reversible: the field is written to put a share out of
+ * sight and removed to bring it back. It says nothing to the donor and nothing about whether
+ * anything was ever copied out of the share — a share can be copied from any number of times,
+ * before or after being hidden.
+ *
+ * The field name keeps its original `decision/` prefix. Records written before hiding replaced
+ * accept/reject carry a different value under the same key, and every reader treats the presence
+ * of the field as the whole answer: someone who accepted or rejected a share back then does not
+ * want to see it, which is exactly what hidden means.
+ */
+export declare const HiddenFieldPrefix = "decision/";
+export declare const hiddenField: (shareId: ShareId) => string;
+export declare const isHiddenField: (name: string) => boolean;
+export declare const hiddenFieldShareId: (name: string) => ShareId;
+export interface ShareHidden {
+  hidden: true;
   timestamp: number;
 }
 /**
@@ -142,42 +203,51 @@ export declare function decodeEnvelopeData(data: Uint8Array): EnvelopeData | und
  */
 export declare function normalizeEnvelopeData(raw: unknown): EnvelopeData | undefined;
 /**
- * Options for {@link MiddleLayer.shareProjects}.
+ * Who a share is granted to: named recipients XOR everyone — two clean variants, not one struct
+ * with mutually exclusive optional fields.
  *
- * Recipients XOR everyone — two clean variants, not one struct with mutually exclusive
- * optional fields. The everyone variant issues a single make-public grant (the envelope's
- * `expiresAt` is set to `null`, so it never expires); the recipients variant grants each
- * named recipient and the envelope expires after the default TTL.
+ * The everyone variant issues a single make-public grant, and the envelope's `expiresAt` is `null`,
+ * so it never expires. The recipients variant grants each named login, and the envelope expires
+ * after the default TTL.
  */
-export type ShareProjectsOptions = {
+export type ShareAudience = {
   recipients: string[];
-  title: string;
-  mode: EnvelopeMode;
 } | {
   everyone: true;
-  /**
-   * When true and an everyone-share of the same project already exists, refresh it under its
-   * stable shareId (recipients who already accepted or rejected are not re-prompted) instead of
-   * minting a new share. No-op when no prior everyone-share of the project exists. Callers that
-   * don't care pass `false`.
-   */
-  replace: boolean;
+};
+/**
+ * Options every share takes: the audience, the title recipients see it under, and the prior
+ * shares it replaces.
+ */
+export type ShareOptions = ShareAudience & {
   title: string;
-  mode: EnvelopeMode;
+  replace?: ShareReplaceOption;
 };
 /**
- * Options for {@link MiddleLayer.shareTemplate}.
+ * Prior shares the new one supersedes: each is deleted in the same transaction that creates the
+ * replacement, so the outbox never holds both.
  *
- * Recipients XOR everyone, exactly as {@link ShareProjectsOptions}, minus the mode: a template
- * share is always granted read-only, because the recipient copies no resource out of the
- * envelope — the document is in the envelope's own data.
+ * The set is the caller's, never inferred here. The author is shown the shares that will go and
+ * agrees to that list, so what was shown has to be what is deleted — an overlap rule computed on
+ * this side would diverge from it. Ids that no longer resolve are skipped: a share revoked between
+ * the dialog opening and the confirm is nothing to undo.
+ *
+ * The replacement is a new {@link ShareId}: a recipient who had hidden the old share sees the new
+ * one, and copies already taken from the old share are untouched.
  */
-export type ShareTemplateOptions = {
-  recipients: string[];
-  title: string;
-} | {
-  everyone: true;
-  title: string;
+export type ShareReplaceOption = ShareId[];
+/** Options for {@link MiddleLayer.shareProjects}: the common ones, plus what the recipient's app
+ *  does with the projects. */
+export type ShareProjectsOptions = ShareOptions & {
+  mode: EnvelopeMode;
+};
+/** Options for {@link MiddleLayer.shareTemplate}. */
+export type ShareTemplateOptions = ShareOptions;
+/** Options for {@link MiddleLayer.shareFolder}. */
+export type ShareFolderOptions = ShareOptions;
+/** What creating a share hands back: the id of the share just created. */
+export type ShareOutcome = {
+  readonly shareId: ShareId;
 };
 //#endregion
 //# sourceMappingURL=sharing_model.d.ts.map

package/dist/model/sharing_model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sharing_model.d.ts","names":[],"sources":["../../src/model/sharing_model.ts"],"mappings":";;;;;;;;;;YAYY,UAAU;;wBAGN,cAAc;;;wBAMd,UAAU,aAAa;;qBAY1B;;qBAEA;qBAEA,2BAA2B;qBAC3B,4BAA4B;qBAC5B,0BAA0B;YAE3B;;;YAIA;;;YAIA,mBAAmB;;;;;;;wBAQf,mBAAmB,MAAM;;;;;;;;;;wBAmBzB,eAAe,MAAM;;;iBAYpB;EACf;EACA,QAAQ;EACR;;;;;;;;;;YAWU;EACN;EAAkB,UAAU,OAAO,kBAAkB;;EAErD;EACA,UAAU;;EAEV;;EAEA;;YAGM,sBAAsB;;;;YAKtB;;qBAGC;;;;;;;;iBASI;EACf,sBAAsB;EACtB,SAAS;EACT;EACA;EACA,MAAM;EACN;EACA;EACA,SAAS;;;;wBAKK,mBAAmB,MAAM,eAAe,OAAO,kBAAkB;;qBAKpE,gBAAa,SAAa;iBAEtB;EACf;EACA;EACA;EACA;;;;;;;;;qBAUW;qBACA,kBAAe;qBACf,oBAAiB;qBACjB,uBAAoB;iBAEhB;EACf;EACA;;;;;;;;;;;wBAYc,mBAAmB,MAAM,aAAa;;;;;;;;;;wBAatC,sBAAsB,eAAe;;;;;;;;;YA+BzC;EAEN;EACA;EACA,MAAM;;EAGN;;;;;;;EAOA;EACA;EACA,MAAM;;;;;;;;;YAUA;EAEN;EACA;;EAGA;EACA"}
+{"version":3,"file":"sharing_model.d.ts","names":[],"sources":["../../src/model/sharing_model.ts"],"mappings":";;;;;;;;;;;YAkBY,UAAU;;wBAGN,cAAc;;;wBAMd,UAAU,aAAa;;qBAY1B;;qBAEA;qBAEA,2BAA2B;qBAC3B,4BAA4B;qBAC5B,0BAA0B;YAE3B;;;YAIA,mBAAmB;;wBAGf,uBAAuB;;;;;;;wBAUvB,mBAAmB,MAAM;;;;;;;;;;wBAmBzB,eAAe,MAAM;;;iBAYpB;EACf;EACA,QAAQ;EACR;;;EAGA;;;;;;;;YASU,mBAAmB;;wBAGf,uBAAuB;;iBAKtB;EACf;;EAEA,SAAS;;EAET;;;iBAIe,8BAA8B;EAC7C,QAAQ;;;;iBAKO;EACf,UAAU;;EAEV;;EAEA;EACA,QAAQ;;;;;;;;;;YAWE;EACN;EAAkB,UAAU,OAAO,kBAAkB;;EAErD;EACA,UAAU;;;;EAIV,SAAS;;EAET;;;EAGA;;EAEA;;EAGA;;;EAGA,QAAQ;;EAER,SAAS,OAAO,kBAAkB;;;EAGlC,UAAU,OAAO,kBAAkB;;EAEnC,WAAW;;EAEX;;YAGM,sBAAsB;;;;YAKtB;;qBAGC;;;;;;;;iBASI;EACf,sBAAsB;EACtB,SAAS;EACT;EACA;EACA,MAAM;EACN;EACA;EACA,SAAS;;;;wBAKK,mBAAmB,MAAM,eAAe,OAAO,kBAAkB;;;;;;;;wBAWjE,mBACd,SAAS,OAAO,kBAAkB,kBACjC;;;;;;;;;;;;;;qBAoBU;qBACA,cAAW,SAAa;qBACxB,gBAAa;qBACb,qBAAkB,iBAAmB;iBAGjC;EACf;EACA;;;;;;;;;;;wBAYc,mBAAmB,MAAM,aAAa;;;;;;;;;;wBAatC,sBAAsB,eAAe;;;;;;;;;YA+BzC;EACN;;EACA;;;;;;YAMM,eAAe;EACzB;EACA,UAAU;;;;;;;;;;;;;;YAeA,qBAAqB;;;YAIrB,uBAAuB;EAAiB,MAAM;;;YAG9C,uBAAuB;;YAGvB,qBAAqB;;YAGrB;WAA0B,SAAS"}

package/dist/model/sharing_model.js

@@ -12,7 +12,7 @@ function asShareId(id) {
 }
 /** Field on the donor's clientRoot holding the {@link SharingOutboxResourceType} resource. */
 const SharingOutboxField = "sharingOutbox";
-/** Field on the acceptor's clientRoot holding the {@link SharingStateResourceType} resource. */
+/** Field on the recipient's clientRoot holding the {@link SharingStateResourceType} resource. */
 const SharingStateField = "sharingState";
 const SharingOutboxResourceType = {
 	name: "SharingOutbox",
@@ -26,6 +26,10 @@ const SharingStateResourceType = {
 	name: "SharingState",
 	version: "1"
 };
+/** Mints a fresh {@link ProjectFieldUuid} for one snapshot. */
+function newProjectFieldUuid() {
+	return randomUUID();
+}
 /**
 * Whether a role may make a resource public (grant to everyone): true for controller,
 * admin; false for workflow and unspecified. The middle layer carries no policy
@@ -55,6 +59,10 @@ function canImpersonate(role) {
 		default: return false;
 	}
 }
+/** Mints a fresh {@link EnvelopeFolderId} for one folder of the envelope being built. */
+function newEnvelopeFolderId() {
+	return randomUUID();
+}
 /** Version written into every new envelope. Bumped from 1 when the payload became discriminated. */
 const EnvelopeSchemaVersionCurrent = 2;
 /** The project map of a projects-payload envelope, or `{}` for any other payload — the one
@@ -62,19 +70,34 @@ const EnvelopeSchemaVersionCurrent = 2;
 function envelopeProjectMap(data) {
 	return data.payload.kind === "projects" ? data.payload.projects : {};
 }
-/** Dynamic field on SharingState, one per handled share, keyed by shareId. */
-const decisionField = (shareId) => `decision/${shareId}`;
-/** Dynamic field on SharedEnvelope, one per recipient who accepted or rejected, keyed
-*  by recipient login. Written by the acceptor in read-write shares only (Copy & Share,
-*  Live collaboration) — the acceptor's writable envelope grant is what permits the
-*  write; read-only shares omit it. The donor reads these from its own outbox to see
-*  who responded and when. Informational, not authoritative (a writable grant holder
-*  could write under another login — same trust assumption as the sender field).
-*  Copied forward when a share is changed. */
-const AcceptanceFieldPrefix = "acceptance/";
-const acceptanceField = (login) => `${AcceptanceFieldPrefix}${login}`;
-const isAcceptanceField = (name) => name.startsWith(AcceptanceFieldPrefix);
-const acceptanceFieldLogin = (name) => name.slice(11);
+/**
+* The shared folder itself: the one folder of the subtree that has no parent.
+*
+* Derived rather than stored, so it cannot disagree with the folders beside it. `undefined` for
+* a subtree with no root or more than one, which is an envelope nothing can be reconstructed
+* from — the copy reports it rather than guessing which folder was meant.
+*/
+function envelopeFolderRoot(folders) {
+	const roots = Object.keys(folders).filter((id) => folders[id].parent === void 0);
+	return roots.length === 1 ? roots[0] : void 0;
+}
+/**
+* Dynamic field on SharingState, one per share this user has hidden, keyed by shareId.
+*
+* Hiding is private to the recipient and reversible: the field is written to put a share out of
+* sight and removed to bring it back. It says nothing to the donor and nothing about whether
+* anything was ever copied out of the share — a share can be copied from any number of times,
+* before or after being hidden.
+*
+* The field name keeps its original `decision/` prefix. Records written before hiding replaced
+* accept/reject carry a different value under the same key, and every reader treats the presence
+* of the field as the whole answer: someone who accepted or rejected a share back then does not
+* want to see it, which is exactly what hidden means.
+*/
+const HiddenFieldPrefix = "decision/";
+const hiddenField = (shareId) => `${HiddenFieldPrefix}${shareId}`;
+const isHiddenField = (name) => name.startsWith(HiddenFieldPrefix);
+const hiddenFieldShareId = (name) => asShareId(name.slice(9));
 /**
 * Single owner of the raw-data → {@link EnvelopeData} decode. The envelope's immutable `data`
 * blob is UTF-8 JSON set once at createEphemeral; every site that reads it from a raw resource
@@ -122,7 +145,8 @@ function normalizeEnvelopeData(raw) {
 *  teaching the decoder about it is a compile error, not a share that silently disappears. */
 const KnownPayloadKinds = {
 	projects: true,
-	template: true
+	template: true,
+	folder: true
 };
 /** Every schema version {@link normalizeEnvelopeData} accepts. Keyed by
 *  {@link EnvelopeSchemaVersion}, so widening that union without deciding how the new shape
@@ -132,6 +156,6 @@ const ReadableSchemaVersions = {
 	2: true
 };
 //#endregion
-export { AcceptanceFieldPrefix, EnvelopeSchemaVersionCurrent, SharedEnvelopeResourceType, SharingOutboxField, SharingOutboxResourceType, SharingStateField, SharingStateResourceType, acceptanceField, acceptanceFieldLogin, asShareId, canGrantToEveryone, canImpersonate, decisionField, decodeEnvelopeData, envelopeProjectMap, isAcceptanceField, newShareId, normalizeEnvelopeData };
+export { EnvelopeSchemaVersionCurrent, HiddenFieldPrefix, SharedEnvelopeResourceType, SharingOutboxField, SharingOutboxResourceType, SharingStateField, SharingStateResourceType, asShareId, canGrantToEveryone, canImpersonate, decodeEnvelopeData, envelopeFolderRoot, envelopeProjectMap, hiddenField, hiddenFieldShareId, isHiddenField, newEnvelopeFolderId, newProjectFieldUuid, newShareId, normalizeEnvelopeData };
 
 //# sourceMappingURL=sharing_model.js.map

package/dist/model/sharing_model.js.map

@@ -1 +1 @@
-{"version":3,"file":"sharing_model.js","names":["RoleEnum"],"sources":["../../src/model/sharing_model.ts"],"sourcesContent":["import type { ResourceType, Role } from \"@milaboratories/pl-client\";\nimport { Role as RoleEnum } from \"@milaboratories/pl-client\";\nimport type { Branded, ProjectId, ProjectTemplateV1 } from \"@milaboratories/pl-model-common\";\nimport { randomUUID } from \"node:crypto\";\n\n/**\n * Logical identity of a share, stable across replaces. A donor-generated UUID string,\n * branded so it cannot be silently confused with a project id, a login, or a raw field\n * name. Minted once with {@link newShareId}; every other site receives it (from decoded\n * {@link EnvelopeData} or by parsing a `decision/{shareId}` field name) and threads it\n * through unchanged.\n */\nexport type ShareId = Branded<string, \"ShareId\">;\n\n/** Mints a fresh {@link ShareId}. The single place a share's logical identity is created. */\nexport function newShareId(): ShareId {\n  return randomUUID() as ShareId;\n}\n\n/** Brands a string already known to be a share id (e.g. parsed from a `decision/{shareId}`\n *  field name) as a {@link ShareId}, without minting a new one. */\nexport function asShareId(id: string): ShareId {\n  return id as ShareId;\n}\n\n//\n// Pl Model — Project Sharing\n//\n// All sharing structures are defined and managed by the middle layer; the\n// backend knows nothing about envelopes.\n//\n\n/** Field on the donor's clientRoot holding the {@link SharingOutboxResourceType} resource. */\nexport const SharingOutboxField = \"sharingOutbox\";\n/** Field on the acceptor's clientRoot holding the {@link SharingStateResourceType} resource. */\nexport const SharingStateField = \"sharingState\";\n\nexport const SharingOutboxResourceType: ResourceType = { name: \"SharingOutbox\", version: \"1\" };\nexport const SharedEnvelopeResourceType: ResourceType = { name: \"SharedEnvelope\", version: \"1\" };\nexport const SharingStateResourceType: ResourceType = { name: \"SharingState\", version: \"1\" };\n\nexport type EnvelopeMode = \"copy\" | \"read-only\" | \"collaboration\";\n\n/** Per-project decision on change, matching the UI labels: re-snapshot the live source (\"update\"),\n *  carry the existing snapshot (\"keep\"), or drop the project from the pack (\"remove\"). */\nexport type ProjectChangeAction = \"keep\" | \"update\" | \"remove\";\n\n/** Key of the per-project envelope maps: a uuid minted per snapshot to name the `project/{uuid}`\n *  field. Distinct from {@link ProjectId} — re-snapshotting one source yields a new uuid each time. */\nexport type ProjectFieldUuid = Branded<string, \"ProjectFieldUuid\">;\n\n/**\n * Whether a role may make a resource public (grant to everyone): true for controller,\n * admin; false for workflow and unspecified. The middle layer carries no policy\n * of its own here — a crafted call still hits the backend's role + permission-ceiling gate.\n * `null` (no-auth mode) returns false.\n */\nexport function canGrantToEveryone(role: Role | null): boolean {\n  switch (role) {\n    case RoleEnum.CONTROLLER:\n    case RoleEnum.ADMIN:\n      return true;\n    default:\n      return false;\n  }\n}\n\n/**\n * Whether a role may impersonate another user: open/create another user's root and list\n * the resources that user can access. Mirrors the backend's authorization rule\n * `util/misecurity/role.go` `CanImpersonate` — true for controller and admin only. This is\n * the admin gate for the \"open another user's root\" feature and is intentionally stricter\n * than {@link canGrantToEveryone}, which also returns true for a regular user (a normal user\n * may share their own projects, but must never be offered impersonation). `null` (no-auth\n * mode) returns false.\n */\nexport function canImpersonate(role: Role | null): boolean {\n  switch (role) {\n    case RoleEnum.CONTROLLER:\n    case RoleEnum.ADMIN:\n      return true;\n    default:\n      return false;\n  }\n}\n\n/** One project's snapshot inside an envelope, keyed by {@link ProjectFieldUuid} in a\n *  `projects` {@link EnvelopePayload}. */\nexport interface EnvelopeProject {\n  label: string; // carried so the pending-share UI renders without traversing into the project\n  source: ProjectId; // donor's source projectId; supersedes a prior share and matches the snapshot to its live source on change\n  updatedAt: number; // ms epoch of the last (re)snapshot\n}\n\n/**\n * What a share carries. The discriminant is what a reader checks before anything else: a\n * client that does not know a kind hides the share instead of offering something it cannot\n * act on.\n *\n * `projects` snapshots ride as `project/{uuid}` fields on the envelope and this map only\n * describes them; a `template` payload has no fields at all — the document is right here.\n */\nexport type EnvelopePayload =\n  | { kind: \"projects\"; projects: Record<ProjectFieldUuid, EnvelopeProject> }\n  | {\n      kind: \"template\";\n      document: ProjectTemplateV1;\n      /** Label to give the template on the recipient's own shelf. */\n      label: string;\n      /** Donor login, kept on the accepted template as its provenance. */\n      from: string;\n    };\n\nexport type EnvelopePayloadKind = EnvelopePayload[\"kind\"];\n\n/** Every envelope schema version this build can read. Adding a version here is what makes\n *  {@link normalizeEnvelopeData} accept it; bumping {@link EnvelopeSchemaVersionCurrent} to a\n *  version missing from this union is a compile error. */\nexport type EnvelopeSchemaVersion = 1 | 2;\n\n/** Version written into every new envelope. Bumped from 1 when the payload became discriminated. */\nexport const EnvelopeSchemaVersionCurrent = 2 satisfies EnvelopeSchemaVersion;\n\n/**\n * Immutable `data` on a SharedEnvelope, set at createEphemeral, never mutated.\n *\n * Always the current version in memory: a v1 envelope (project map at the top level, no\n * `payload` field) is upcast on read by {@link normalizeEnvelopeData}, so no reader past the\n * decode has to know that two shapes ever existed.\n */\nexport interface EnvelopeData {\n  schemaVersion: typeof EnvelopeSchemaVersionCurrent;\n  shareId: ShareId; // donor-generated UUID; logical share identity, stable across changes\n  sharedAt: number; // ms epoch; this instance's creation time — distinguishes instances of one shareId\n  expiresAt: number | null; // ms epoch; sharedAt + ttl (default 14 days) for a targeted share; null for share-with-everybody (never expires)\n  mode: EnvelopeMode; // what the acceptor's app should do with the contents\n  sender: string; // donor login (informational; backend granted_by is authoritative)\n  title: string; // display name shown to recipients; defaults to the first project's name\n  payload: EnvelopePayload; // what the share carries\n}\n\n/** The project map of a projects-payload envelope, or `{}` for any other payload — the one\n *  place a project-shaped reader turns a payload into the map it expects. */\nexport function envelopeProjectMap(data: EnvelopeData): Record<ProjectFieldUuid, EnvelopeProject> {\n  return data.payload.kind === \"projects\" ? data.payload.projects : {};\n}\n\n/** Dynamic field on SharingState, one per handled share, keyed by shareId. */\nexport const decisionField = (shareId: ShareId) => `decision/${shareId}`;\n\nexport interface SharingDecision {\n  decision: \"accepted\" | \"rejected\";\n  timestamp: number; // ms epoch — when the acceptor acted\n  envelopeSharedAt: number; // the acted-on envelope instance's sharedAt — pins which instance was handled (paired with the shareId key; the resource id is never stored)\n  acceptedProjects: string[]; // ids of the projects created in the acceptor's list ([] for a rejected share, and for a template share, which creates none)\n}\n\n/** Dynamic field on SharedEnvelope, one per recipient who accepted or rejected, keyed\n *  by recipient login. Written by the acceptor in read-write shares only (Copy & Share,\n *  Live collaboration) — the acceptor's writable envelope grant is what permits the\n *  write; read-only shares omit it. The donor reads these from its own outbox to see\n *  who responded and when. Informational, not authoritative (a writable grant holder\n *  could write under another login — same trust assumption as the sender field).\n *  Copied forward when a share is changed. */\nexport const AcceptanceFieldPrefix = \"acceptance/\";\nexport const acceptanceField = (login: string) => `${AcceptanceFieldPrefix}${login}`;\nexport const isAcceptanceField = (name: string) => name.startsWith(AcceptanceFieldPrefix);\nexport const acceptanceFieldLogin = (name: string) => name.slice(AcceptanceFieldPrefix.length);\n\nexport interface EnvelopeAcceptance {\n  action: \"accepted\" | \"rejected\";\n  timestamp: number; // ms since epoch\n}\n\n/**\n * Single owner of the raw-data → {@link EnvelopeData} decode. The envelope's immutable `data`\n * blob is UTF-8 JSON set once at createEphemeral; every site that reads it from a raw resource\n * `data` byte buffer (the basic-resource read path) goes through here. The reactive tree-node\n * path decodes the same JSON with `getDataAsJson` and normalizes it with\n * {@link normalizeEnvelopeData} — both paths must, so neither sees the raw v1 shape.\n *\n * `undefined` for an envelope this build cannot act on; see {@link normalizeEnvelopeData}.\n */\nexport function decodeEnvelopeData(data: Uint8Array): EnvelopeData | undefined {\n  return normalizeEnvelopeData(JSON.parse(Buffer.from(data).toString(\"utf-8\")));\n}\n\n/**\n * Brings a decoded envelope blob to the current shape, or reports that this build cannot act\n * on it by returning `undefined` — an unknown `schemaVersion` or an unknown payload kind. A\n * caller hides such a share rather than offering the recipient something it cannot handle.\n *\n * A v1 envelope carried its project map at the top level and had no `payload` field; it reads\n * here as a `projects` payload, so envelopes written before the discriminant existed keep\n * working unchanged.\n */\nexport function normalizeEnvelopeData(raw: unknown): EnvelopeData | undefined {\n  if (typeof raw !== \"object\" || raw === null) return undefined;\n  const e = raw as RawEnvelopeData;\n  if (!Object.hasOwn(ReadableSchemaVersions, e.schemaVersion)) return undefined;\n\n  const payload =\n    e.payload ??\n    (e.projects !== undefined ? ({ kind: \"projects\", projects: e.projects } as const) : undefined);\n  if (payload === undefined) return undefined;\n  if (!Object.hasOwn(KnownPayloadKinds, payload.kind)) return undefined;\n\n  return {\n    schemaVersion: EnvelopeSchemaVersionCurrent,\n    shareId: e.shareId,\n    sharedAt: e.sharedAt,\n    expiresAt: e.expiresAt,\n    mode: e.mode,\n    sender: e.sender,\n    title: e.title,\n    payload,\n  };\n}\n\n/**\n * Options for {@link MiddleLayer.shareProjects}.\n *\n * Recipients XOR everyone — two clean variants, not one struct with mutually exclusive\n * optional fields. The everyone variant issues a single make-public grant (the envelope's\n * `expiresAt` is set to `null`, so it never expires); the recipients variant grants each\n * named recipient and the envelope expires after the default TTL.\n */\nexport type ShareProjectsOptions =\n  | {\n      recipients: string[]; // recipient logins\n      title: string; // display name shown to recipients; defaults to the first project's name\n      mode: EnvelopeMode; // v1 UI always sends \"copy\"\n    }\n  | {\n      everyone: true; // share with all users on the server\n      /**\n       * When true and an everyone-share of the same project already exists, refresh it under its\n       * stable shareId (recipients who already accepted or rejected are not re-prompted) instead of\n       * minting a new share. No-op when no prior everyone-share of the project exists. Callers that\n       * don't care pass `false`.\n       */\n      replace: boolean;\n      title: string;\n      mode: EnvelopeMode;\n    };\n\n/**\n * Options for {@link MiddleLayer.shareTemplate}.\n *\n * Recipients XOR everyone, exactly as {@link ShareProjectsOptions}, minus the mode: a template\n * share is always granted read-only, because the recipient copies no resource out of the\n * envelope — the document is in the envelope's own data.\n */\nexport type ShareTemplateOptions =\n  | {\n      recipients: string[]; // recipient logins\n      title: string; // display name shown to recipients; defaults to the template's label\n    }\n  | {\n      everyone: true; // share with all users on the server\n      title: string;\n    };\n\n//\n// Internals\n//\n\n/** Every payload kind this build can act on; anything else is hidden rather than offered.\n *  Keyed by {@link EnvelopePayloadKind}, so adding a kind to {@link EnvelopePayload} without\n *  teaching the decoder about it is a compile error, not a share that silently disappears. */\nconst KnownPayloadKinds: Record<EnvelopePayloadKind, true> = {\n  projects: true,\n  template: true,\n};\n\n/** Every schema version {@link normalizeEnvelopeData} accepts. Keyed by\n *  {@link EnvelopeSchemaVersion}, so widening that union without deciding how the new shape\n *  is upcast is a compile error. */\nconst ReadableSchemaVersions: Record<EnvelopeSchemaVersion, true> = {\n  1: true,\n  2: true,\n};\n\n/**\n * The envelope blob as it comes off the wire, before {@link normalizeEnvelopeData} decides\n * whether this build can act on it: the version is any number, the payload may be missing,\n * and `projects` is the v1 top-level project map.\n */\ntype RawEnvelopeData = Omit<EnvelopeData, \"schemaVersion\" | \"payload\"> & {\n  schemaVersion: number;\n  payload?: EnvelopePayload;\n  projects?: Record<ProjectFieldUuid, EnvelopeProject>;\n};\n"],"mappings":";;;;AAeA,SAAgB,aAAsB;CACpC,OAAO,WAAW;AACpB;;;AAIA,SAAgB,UAAU,IAAqB;CAC7C,OAAO;AACT;;AAUA,MAAa,qBAAqB;;AAElC,MAAa,oBAAoB;AAEjC,MAAa,4BAA0C;CAAE,MAAM;CAAiB,SAAS;AAAI;AAC7F,MAAa,6BAA2C;CAAE,MAAM;CAAkB,SAAS;AAAI;AAC/F,MAAa,2BAAyC;CAAE,MAAM;CAAgB,SAAS;AAAI;;;;;;;AAkB3F,SAAgB,mBAAmB,MAA4B;CAC7D,QAAQ,MAAR;EACE,KAAKA,KAAS;EACd,KAAKA,KAAS,OACZ,OAAO;EACT,SACE,OAAO;CACX;AACF;;;;;;;;;;AAWA,SAAgB,eAAe,MAA4B;CACzD,QAAQ,MAAR;EACE,KAAKA,KAAS;EACd,KAAKA,KAAS,OACZ,OAAO;EACT,SACE,OAAO;CACX;AACF;;AAqCA,MAAa,+BAA+B;;;AAsB5C,SAAgB,mBAAmB,MAA+D;CAChG,OAAO,KAAK,QAAQ,SAAS,aAAa,KAAK,QAAQ,WAAW,CAAC;AACrE;;AAGA,MAAa,iBAAiB,YAAqB,YAAY;;;;;;;;AAgB/D,MAAa,wBAAwB;AACrC,MAAa,mBAAmB,UAAkB,GAAG,wBAAwB;AAC7E,MAAa,qBAAqB,SAAiB,KAAK,WAAW,qBAAqB;AACxF,MAAa,wBAAwB,SAAiB,KAAK,MAAM,EAA4B;;;;;;;;;;AAgB7F,SAAgB,mBAAmB,MAA4C;CAC7E,OAAO,sBAAsB,KAAK,MAAM,OAAO,KAAK,IAAI,CAAC,CAAC,SAAS,OAAO,CAAC,CAAC;AAC9E;;;;;;;;;;AAWA,SAAgB,sBAAsB,KAAwC;CAC5E,IAAI,OAAO,QAAQ,YAAY,QAAQ,MAAM,OAAO,KAAA;CACpD,MAAM,IAAI;CACV,IAAI,CAAC,OAAO,OAAO,wBAAwB,EAAE,aAAa,GAAG,OAAO,KAAA;CAEpE,MAAM,UACJ,EAAE,YACD,EAAE,aAAa,KAAA,IAAa;EAAE,MAAM;EAAY,UAAU,EAAE;CAAS,IAAc,KAAA;CACtF,IAAI,YAAY,KAAA,GAAW,OAAO,KAAA;CAClC,IAAI,CAAC,OAAO,OAAO,mBAAmB,QAAQ,IAAI,GAAG,OAAO,KAAA;CAE5D,OAAO;EACL,eAAA;EACA,SAAS,EAAE;EACX,UAAU,EAAE;EACZ,WAAW,EAAE;EACb,MAAM,EAAE;EACR,QAAQ,EAAE;EACV,OAAO,EAAE;EACT;CACF;AACF;;;;AAqDA,MAAM,oBAAuD;CAC3D,UAAU;CACV,UAAU;AACZ;;;;AAKA,MAAM,yBAA8D;CAClE,GAAG;CACH,GAAG;AACL"}
+{"version":3,"file":"sharing_model.js","names":["RoleEnum"],"sources":["../../src/model/sharing_model.ts"],"sourcesContent":["import type { ResourceType, Role } from \"@milaboratories/pl-client\";\nimport { Role as RoleEnum } from \"@milaboratories/pl-client\";\nimport type {\n  Branded,\n  ProjectId,\n  ProjectTemplateV1,\n  TemplateId,\n} from \"@milaboratories/pl-model-common\";\nimport type { FolderId } from \"@milaboratories/pl-model-middle-layer\";\nimport { randomUUID } from \"node:crypto\";\n\n/**\n * Identity of one share. A donor-generated UUID string,\n * branded so it cannot be silently confused with a project id, a login, or a raw field\n * name. Minted once with {@link newShareId}; every other site receives it (from decoded\n * {@link EnvelopeData} or by parsing a `decision/{shareId}` field name) and threads it\n * through unchanged.\n */\nexport type ShareId = Branded<string, \"ShareId\">;\n\n/** Mints a fresh {@link ShareId}. The single place a share's logical identity is created. */\nexport function newShareId(): ShareId {\n  return randomUUID() as ShareId;\n}\n\n/** Brands a string already known to be a share id (e.g. parsed from a `decision/{shareId}`\n *  field name) as a {@link ShareId}, without minting a new one. */\nexport function asShareId(id: string): ShareId {\n  return id as ShareId;\n}\n\n//\n// Pl Model — Project Sharing\n//\n// All sharing structures are defined and managed by the middle layer; the\n// backend knows nothing about envelopes.\n//\n\n/** Field on the donor's clientRoot holding the {@link SharingOutboxResourceType} resource. */\nexport const SharingOutboxField = \"sharingOutbox\";\n/** Field on the recipient's clientRoot holding the {@link SharingStateResourceType} resource. */\nexport const SharingStateField = \"sharingState\";\n\nexport const SharingOutboxResourceType: ResourceType = { name: \"SharingOutbox\", version: \"1\" };\nexport const SharedEnvelopeResourceType: ResourceType = { name: \"SharedEnvelope\", version: \"1\" };\nexport const SharingStateResourceType: ResourceType = { name: \"SharingState\", version: \"1\" };\n\nexport type EnvelopeMode = \"copy\" | \"read-only\" | \"collaboration\";\n\n/** Key of the per-project envelope maps: a uuid minted per snapshot to name the `project/{uuid}`\n *  field. Distinct from {@link ProjectId} — re-snapshotting one source yields a new uuid each time. */\nexport type ProjectFieldUuid = Branded<string, \"ProjectFieldUuid\">;\n\n/** Mints a fresh {@link ProjectFieldUuid} for one snapshot. */\nexport function newProjectFieldUuid(): ProjectFieldUuid {\n  return randomUUID() as ProjectFieldUuid;\n}\n\n/**\n * Whether a role may make a resource public (grant to everyone): true for controller,\n * admin; false for workflow and unspecified. The middle layer carries no policy\n * of its own here — a crafted call still hits the backend's role + permission-ceiling gate.\n * `null` (no-auth mode) returns false.\n */\nexport function canGrantToEveryone(role: Role | null): boolean {\n  switch (role) {\n    case RoleEnum.CONTROLLER:\n    case RoleEnum.ADMIN:\n      return true;\n    default:\n      return false;\n  }\n}\n\n/**\n * Whether a role may impersonate another user: open/create another user's root and list\n * the resources that user can access. Mirrors the backend's authorization rule\n * `util/misecurity/role.go` `CanImpersonate` — true for controller and admin only. This is\n * the admin gate for the \"open another user's root\" feature and is intentionally stricter\n * than {@link canGrantToEveryone}, which also returns true for a regular user (a normal user\n * may share their own projects, but must never be offered impersonation). `null` (no-auth\n * mode) returns false.\n */\nexport function canImpersonate(role: Role | null): boolean {\n  switch (role) {\n    case RoleEnum.CONTROLLER:\n    case RoleEnum.ADMIN:\n      return true;\n    default:\n      return false;\n  }\n}\n\n/** One project's snapshot inside an envelope, keyed by {@link ProjectFieldUuid} in a\n *  `projects` {@link EnvelopePayload}. */\nexport interface EnvelopeProject {\n  label: string; // carried so the share lists render without traversing into the project\n  source: ProjectId; // donor's source projectId; what a prior share of the same project is matched on\n  updatedAt: number; // ms epoch of the last (re)snapshot\n  /** What the project said about itself when it was snapshotted, carried for the same reason as\n   *  `label`. Absent when it had none, and on envelopes written before it was carried. */\n  description?: string;\n}\n\n/**\n * Identifier of a folder inside one envelope.\n *\n * Local to the envelope, because the recipient's own folder document mints its own ids and the\n * donor's mean nothing there. What travels is the shape of the subtree, not its identity.\n */\nexport type EnvelopeFolderId = Branded<string, \"EnvelopeFolderId\">;\n\n/** Mints a fresh {@link EnvelopeFolderId} for one folder of the envelope being built. */\nexport function newEnvelopeFolderId(): EnvelopeFolderId {\n  return randomUUID() as EnvelopeFolderId;\n}\n\n/** One folder of a shared subtree. */\nexport interface EnvelopeFolder {\n  name: string;\n  /** Absent for the subtree's root — the folder that was shared. */\n  parent?: EnvelopeFolderId;\n  /** What the donor wrote about the folder. Absent when there is none. */\n  description?: string;\n}\n\n/** A project of a shared subtree: an {@link EnvelopeProject} placed in the subtree. */\nexport interface EnvelopeFolderProject extends EnvelopeProject {\n  folder: EnvelopeFolderId;\n}\n\n/** A template of a shared subtree. The document rides here whole, exactly as a `template`\n *  payload carries it — a template is never snapshotted. */\nexport interface EnvelopeFolderTemplate {\n  document: ProjectTemplateV1;\n  /** Label to give the template among the recipient's templates. */\n  label: string;\n  /** What the template says about itself. Absent when the donor described it with nothing. */\n  description?: string;\n  folder: EnvelopeFolderId;\n}\n\n/**\n * What a share carries. The discriminant is what a reader checks before anything else: a\n * client that does not know a kind hides the share instead of offering something it cannot\n * act on.\n *\n * `projects` snapshots ride as `project/{uuid}` fields on the envelope and this map only\n * describes them; a `template` payload has no fields at all — the document is right here.\n */\nexport type EnvelopePayload =\n  | { kind: \"projects\"; projects: Record<ProjectFieldUuid, EnvelopeProject> }\n  | {\n      kind: \"template\";\n      document: ProjectTemplateV1;\n      /** Donor's own id of the shared template; what a prior share of the same template is\n       *  matched on. It names nothing in the recipient's tree, and envelopes written before it\n       *  existed carry none — those match no later share of anything. */\n      source?: TemplateId;\n      /** Label to give the template among the recipient's templates. */\n      label: string;\n      /** What the template says about itself, carried to the recipient's copy. Absent when the\n       *  donor described it with nothing. */\n      description?: string;\n      /** Donor login, kept on each copy of the template as its provenance. */\n      from: string;\n    }\n  | {\n      kind: \"folder\";\n      /** Donor's own id of the shared folder; what a prior share of the same folder is matched\n       *  on. It names nothing in the recipient's tree. */\n      source: FolderId;\n      /** The shared subtree. Exactly one folder has no parent, and that one is its root. */\n      folders: Record<EnvelopeFolderId, EnvelopeFolder>;\n      /** Project snapshots, each tagged with the folder of the subtree holding it. Their\n       *  `project/{uuid}` fields are the same ones a `projects` payload describes. */\n      projects: Record<ProjectFieldUuid, EnvelopeFolderProject>;\n      /** Templates of the subtree, documents and all. Nothing of a template is snapshotted. */\n      templates: EnvelopeFolderTemplate[];\n      /** Donor login, kept on each copied template as its provenance. */\n      from: string;\n    };\n\nexport type EnvelopePayloadKind = EnvelopePayload[\"kind\"];\n\n/** Every envelope schema version this build can read. Adding a version here is what makes\n *  {@link normalizeEnvelopeData} accept it; bumping {@link EnvelopeSchemaVersionCurrent} to a\n *  version missing from this union is a compile error. */\nexport type EnvelopeSchemaVersion = 1 | 2;\n\n/** Version written into every new envelope. Bumped from 1 when the payload became discriminated. */\nexport const EnvelopeSchemaVersionCurrent = 2 satisfies EnvelopeSchemaVersion;\n\n/**\n * Immutable `data` on a SharedEnvelope, set at createEphemeral, never mutated.\n *\n * Always the current version in memory: a v1 envelope (project map at the top level, no\n * `payload` field) is upcast on read by {@link normalizeEnvelopeData}, so no reader past the\n * decode has to know that two shapes ever existed.\n */\nexport interface EnvelopeData {\n  schemaVersion: typeof EnvelopeSchemaVersionCurrent;\n  shareId: ShareId; // donor-generated UUID; identity of this share alone\n  sharedAt: number; // ms epoch; when the share was created\n  expiresAt: number | null; // ms epoch; sharedAt + ttl (default 14 days) for a targeted share; null for share-with-everybody (never expires)\n  mode: EnvelopeMode; // what the recipient's app should do with the contents\n  sender: string; // donor login (informational; backend granted_by is authoritative)\n  title: string; // display name shown to recipients; defaults to the first project's name\n  payload: EnvelopePayload; // what the share carries\n}\n\n/** The project map of a projects-payload envelope, or `{}` for any other payload — the one\n *  place a project-shaped reader turns a payload into the map it expects. */\nexport function envelopeProjectMap(data: EnvelopeData): Record<ProjectFieldUuid, EnvelopeProject> {\n  return data.payload.kind === \"projects\" ? data.payload.projects : {};\n}\n\n/**\n * The shared folder itself: the one folder of the subtree that has no parent.\n *\n * Derived rather than stored, so it cannot disagree with the folders beside it. `undefined` for\n * a subtree with no root or more than one, which is an envelope nothing can be reconstructed\n * from — the copy reports it rather than guessing which folder was meant.\n */\nexport function envelopeFolderRoot(\n  folders: Record<EnvelopeFolderId, EnvelopeFolder>,\n): EnvelopeFolderId | undefined {\n  const roots = (Object.keys(folders) as EnvelopeFolderId[]).filter(\n    (id) => folders[id].parent === undefined,\n  );\n  return roots.length === 1 ? roots[0] : undefined;\n}\n\n/**\n * Dynamic field on SharingState, one per share this user has hidden, keyed by shareId.\n *\n * Hiding is private to the recipient and reversible: the field is written to put a share out of\n * sight and removed to bring it back. It says nothing to the donor and nothing about whether\n * anything was ever copied out of the share — a share can be copied from any number of times,\n * before or after being hidden.\n *\n * The field name keeps its original `decision/` prefix. Records written before hiding replaced\n * accept/reject carry a different value under the same key, and every reader treats the presence\n * of the field as the whole answer: someone who accepted or rejected a share back then does not\n * want to see it, which is exactly what hidden means.\n */\nexport const HiddenFieldPrefix = \"decision/\";\nexport const hiddenField = (shareId: ShareId) => `${HiddenFieldPrefix}${shareId}`;\nexport const isHiddenField = (name: string) => name.startsWith(HiddenFieldPrefix);\nexport const hiddenFieldShareId = (name: string): ShareId =>\n  asShareId(name.slice(HiddenFieldPrefix.length));\n\nexport interface ShareHidden {\n  hidden: true;\n  timestamp: number; // ms epoch — when the recipient hid it\n}\n\n/**\n * Single owner of the raw-data → {@link EnvelopeData} decode. The envelope's immutable `data`\n * blob is UTF-8 JSON set once at createEphemeral; every site that reads it from a raw resource\n * `data` byte buffer (the basic-resource read path) goes through here. The reactive tree-node\n * path decodes the same JSON with `getDataAsJson` and normalizes it with\n * {@link normalizeEnvelopeData} — both paths must, so neither sees the raw v1 shape.\n *\n * `undefined` for an envelope this build cannot act on; see {@link normalizeEnvelopeData}.\n */\nexport function decodeEnvelopeData(data: Uint8Array): EnvelopeData | undefined {\n  return normalizeEnvelopeData(JSON.parse(Buffer.from(data).toString(\"utf-8\")));\n}\n\n/**\n * Brings a decoded envelope blob to the current shape, or reports that this build cannot act\n * on it by returning `undefined` — an unknown `schemaVersion` or an unknown payload kind. A\n * caller hides such a share rather than offering the recipient something it cannot handle.\n *\n * A v1 envelope carried its project map at the top level and had no `payload` field; it reads\n * here as a `projects` payload, so envelopes written before the discriminant existed keep\n * working unchanged.\n */\nexport function normalizeEnvelopeData(raw: unknown): EnvelopeData | undefined {\n  if (typeof raw !== \"object\" || raw === null) return undefined;\n  const e = raw as RawEnvelopeData;\n  if (!Object.hasOwn(ReadableSchemaVersions, e.schemaVersion)) return undefined;\n\n  const payload =\n    e.payload ??\n    (e.projects !== undefined ? ({ kind: \"projects\", projects: e.projects } as const) : undefined);\n  if (payload === undefined) return undefined;\n  if (!Object.hasOwn(KnownPayloadKinds, payload.kind)) return undefined;\n\n  return {\n    schemaVersion: EnvelopeSchemaVersionCurrent,\n    shareId: e.shareId,\n    sharedAt: e.sharedAt,\n    expiresAt: e.expiresAt,\n    mode: e.mode,\n    sender: e.sender,\n    title: e.title,\n    payload,\n  };\n}\n\n/**\n * Who a share is granted to: named recipients XOR everyone — two clean variants, not one struct\n * with mutually exclusive optional fields.\n *\n * The everyone variant issues a single make-public grant, and the envelope's `expiresAt` is `null`,\n * so it never expires. The recipients variant grants each named login, and the envelope expires\n * after the default TTL.\n */\nexport type ShareAudience =\n  | { recipients: string[] } // recipient logins\n  | { everyone: true }; // every user on the server\n\n/**\n * Options every share takes: the audience, the title recipients see it under, and the prior\n * shares it replaces.\n */\nexport type ShareOptions = ShareAudience & {\n  title: string;\n  replace?: ShareReplaceOption;\n};\n\n/**\n * Prior shares the new one supersedes: each is deleted in the same transaction that creates the\n * replacement, so the outbox never holds both.\n *\n * The set is the caller's, never inferred here. The author is shown the shares that will go and\n * agrees to that list, so what was shown has to be what is deleted — an overlap rule computed on\n * this side would diverge from it. Ids that no longer resolve are skipped: a share revoked between\n * the dialog opening and the confirm is nothing to undo.\n *\n * The replacement is a new {@link ShareId}: a recipient who had hidden the old share sees the new\n * one, and copies already taken from the old share are untouched.\n */\nexport type ShareReplaceOption = ShareId[];\n\n/** Options for {@link MiddleLayer.shareProjects}: the common ones, plus what the recipient's app\n *  does with the projects. */\nexport type ShareProjectsOptions = ShareOptions & { mode: EnvelopeMode };\n\n/** Options for {@link MiddleLayer.shareTemplate}. */\nexport type ShareTemplateOptions = ShareOptions;\n\n/** Options for {@link MiddleLayer.shareFolder}. */\nexport type ShareFolderOptions = ShareOptions;\n\n/** What creating a share hands back: the id of the share just created. */\nexport type ShareOutcome = { readonly shareId: ShareId };\n\n//\n// Internals\n//\n\n/** Every payload kind this build can act on; anything else is hidden rather than offered.\n *  Keyed by {@link EnvelopePayloadKind}, so adding a kind to {@link EnvelopePayload} without\n *  teaching the decoder about it is a compile error, not a share that silently disappears. */\nconst KnownPayloadKinds: Record<EnvelopePayloadKind, true> = {\n  projects: true,\n  template: true,\n  folder: true,\n};\n\n/** Every schema version {@link normalizeEnvelopeData} accepts. Keyed by\n *  {@link EnvelopeSchemaVersion}, so widening that union without deciding how the new shape\n *  is upcast is a compile error. */\nconst ReadableSchemaVersions: Record<EnvelopeSchemaVersion, true> = {\n  1: true,\n  2: true,\n};\n\n/**\n * The envelope blob as it comes off the wire, before {@link normalizeEnvelopeData} decides\n * whether this build can act on it: the version is any number, the payload may be missing,\n * and `projects` is the v1 top-level project map.\n */\ntype RawEnvelopeData = Omit<EnvelopeData, \"schemaVersion\" | \"payload\"> & {\n  schemaVersion: number;\n  payload?: EnvelopePayload;\n  projects?: Record<ProjectFieldUuid, EnvelopeProject>;\n};\n"],"mappings":";;;;AAqBA,SAAgB,aAAsB;CACpC,OAAO,WAAW;AACpB;;;AAIA,SAAgB,UAAU,IAAqB;CAC7C,OAAO;AACT;;AAUA,MAAa,qBAAqB;;AAElC,MAAa,oBAAoB;AAEjC,MAAa,4BAA0C;CAAE,MAAM;CAAiB,SAAS;AAAI;AAC7F,MAAa,6BAA2C;CAAE,MAAM;CAAkB,SAAS;AAAI;AAC/F,MAAa,2BAAyC;CAAE,MAAM;CAAgB,SAAS;AAAI;;AAS3F,SAAgB,sBAAwC;CACtD,OAAO,WAAW;AACpB;;;;;;;AAQA,SAAgB,mBAAmB,MAA4B;CAC7D,QAAQ,MAAR;EACE,KAAKA,KAAS;EACd,KAAKA,KAAS,OACZ,OAAO;EACT,SACE,OAAO;CACX;AACF;;;;;;;;;;AAWA,SAAgB,eAAe,MAA4B;CACzD,QAAQ,MAAR;EACE,KAAKA,KAAS;EACd,KAAKA,KAAS,OACZ,OAAO;EACT,SACE,OAAO;CACX;AACF;;AAsBA,SAAgB,sBAAwC;CACtD,OAAO,WAAW;AACpB;;AA4EA,MAAa,+BAA+B;;;AAsB5C,SAAgB,mBAAmB,MAA+D;CAChG,OAAO,KAAK,QAAQ,SAAS,aAAa,KAAK,QAAQ,WAAW,CAAC;AACrE;;;;;;;;AASA,SAAgB,mBACd,SAC8B;CAC9B,MAAM,QAAS,OAAO,KAAK,OAAO,CAAC,CAAwB,QACxD,OAAO,QAAQ,GAAG,CAAC,WAAW,KAAA,CACjC;CACA,OAAO,MAAM,WAAW,IAAI,MAAM,KAAK,KAAA;AACzC;;;;;;;;;;;;;;AAeA,MAAa,oBAAoB;AACjC,MAAa,eAAe,YAAqB,GAAG,oBAAoB;AACxE,MAAa,iBAAiB,SAAiB,KAAK,WAAW,iBAAiB;AAChF,MAAa,sBAAsB,SACjC,UAAU,KAAK,MAAM,CAAwB,CAAC;;;;;;;;;;AAgBhD,SAAgB,mBAAmB,MAA4C;CAC7E,OAAO,sBAAsB,KAAK,MAAM,OAAO,KAAK,IAAI,CAAC,CAAC,SAAS,OAAO,CAAC,CAAC;AAC9E;;;;;;;;;;AAWA,SAAgB,sBAAsB,KAAwC;CAC5E,IAAI,OAAO,QAAQ,YAAY,QAAQ,MAAM,OAAO,KAAA;CACpD,MAAM,IAAI;CACV,IAAI,CAAC,OAAO,OAAO,wBAAwB,EAAE,aAAa,GAAG,OAAO,KAAA;CAEpE,MAAM,UACJ,EAAE,YACD,EAAE,aAAa,KAAA,IAAa;EAAE,MAAM;EAAY,UAAU,EAAE;CAAS,IAAc,KAAA;CACtF,IAAI,YAAY,KAAA,GAAW,OAAO,KAAA;CAClC,IAAI,CAAC,OAAO,OAAO,mBAAmB,QAAQ,IAAI,GAAG,OAAO,KAAA;CAE5D,OAAO;EACL,eAAA;EACA,SAAS,EAAE;EACX,UAAU,EAAE;EACZ,WAAW,EAAE;EACb,MAAM,EAAE;EACR,QAAQ,EAAE;EACV,OAAO,EAAE;EACT;CACF;AACF;;;;AAyDA,MAAM,oBAAuD;CAC3D,UAAU;CACV,UAAU;CACV,QAAQ;AACV;;;;AAKA,MAAM,yBAA8D;CAClE,GAAG;CACH,GAAG;AACL"}

package/dist/mutator/list.cjs

@@ -0,0 +1,30 @@
+let _milaboratories_pl_client = require("@milaboratories/pl-client");
+//#region src/mutator/list.ts
+/**
+* Every entry of a list resource — the project list or the template list — keyed by the string
+* form of the resource id it points at, which is what a project or template id is.
+*
+* A list field's name is a uuid unrelated to the id of what it holds, so an entry is only ever
+* found by value. Fields that point at nothing yet are left out.
+*/
+async function listedById(tx, listRid) {
+	const data = await tx.getResourceData(listRid, true);
+	const entries = /* @__PURE__ */ new Map();
+	for (const f of data.fields) {
+		if ((0, _milaboratories_pl_client.isNullSignedResourceId)(f.value)) continue;
+		entries.set((0, _milaboratories_pl_client.resourceIdToString)(f.value), {
+			fieldName: f.name,
+			rid: f.value
+		});
+	}
+	return entries;
+}
+/** What is thrown for an id the list does not hold, worded the same for every list. */
+function notListedError(kind, id) {
+	return /* @__PURE__ */ new Error(`${kind} ${id} not found in the ${kind.toLowerCase()} list.`);
+}
+//#endregion
+exports.listedById = listedById;
+exports.notListedError = notListedError;
+
+//# sourceMappingURL=list.cjs.map

package/dist/mutator/list.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.cjs","names":[],"sources":["../../src/mutator/list.ts"],"sourcesContent":["import type { PlTransaction, SignedResourceId } from \"@milaboratories/pl-client\";\nimport { isNullSignedResourceId, resourceIdToString } from \"@milaboratories/pl-client\";\n\n/** One entry of a list resource: the field holding it and the resource that field points at. */\nexport interface ListedEntry {\n  readonly fieldName: string;\n  readonly rid: SignedResourceId;\n}\n\n/** The kinds of list a root keeps, as a not-found message names them. */\nexport type ListedKind = \"Project\" | \"Template\";\n\n/**\n * Every entry of a list resource — the project list or the template list — keyed by the string\n * form of the resource id it points at, which is what a project or template id is.\n *\n * A list field's name is a uuid unrelated to the id of what it holds, so an entry is only ever\n * found by value. Fields that point at nothing yet are left out.\n */\nexport async function listedById(\n  tx: PlTransaction,\n  listRid: SignedResourceId,\n): Promise<Map<string, ListedEntry>> {\n  const data = await tx.getResourceData(listRid, true);\n  const entries = new Map<string, ListedEntry>();\n  for (const f of data.fields) {\n    if (isNullSignedResourceId(f.value)) continue;\n    entries.set(resourceIdToString(f.value), { fieldName: f.name, rid: f.value });\n  }\n  return entries;\n}\n\n/** What is thrown for an id the list does not hold, worded the same for every list. */\nexport function notListedError(kind: ListedKind, id: string): Error {\n  return new Error(`${kind} ${id} not found in the ${kind.toLowerCase()} list.`);\n}\n"],"mappings":";;;;;;;;;AAmBA,eAAsB,WACpB,IACA,SACmC;CACnC,MAAM,OAAO,MAAM,GAAG,gBAAgB,SAAS,IAAI;CACnD,MAAM,0BAAU,IAAI,IAAyB;CAC7C,KAAK,MAAM,KAAK,KAAK,QAAQ;EAC3B,KAAA,GAAA,0BAAA,uBAAA,CAA2B,EAAE,KAAK,GAAG;EACrC,QAAQ,KAAA,GAAA,0BAAA,mBAAA,CAAuB,EAAE,KAAK,GAAG;GAAE,WAAW,EAAE;GAAM,KAAK,EAAE;EAAM,CAAC;CAC9E;CACA,OAAO;AACT;;AAGA,SAAgB,eAAe,MAAkB,IAAmB;CAClE,uBAAO,IAAI,MAAM,GAAG,KAAK,GAAG,GAAG,oBAAoB,KAAK,YAAY,EAAE,OAAO;AAC/E"}

package/dist/mutator/list.js

@@ -0,0 +1,29 @@
+import { isNullSignedResourceId, resourceIdToString } from "@milaboratories/pl-client";
+//#region src/mutator/list.ts
+/**
+* Every entry of a list resource — the project list or the template list — keyed by the string
+* form of the resource id it points at, which is what a project or template id is.
+*
+* A list field's name is a uuid unrelated to the id of what it holds, so an entry is only ever
+* found by value. Fields that point at nothing yet are left out.
+*/
+async function listedById(tx, listRid) {
+	const data = await tx.getResourceData(listRid, true);
+	const entries = /* @__PURE__ */ new Map();
+	for (const f of data.fields) {
+		if (isNullSignedResourceId(f.value)) continue;
+		entries.set(resourceIdToString(f.value), {
+			fieldName: f.name,
+			rid: f.value
+		});
+	}
+	return entries;
+}
+/** What is thrown for an id the list does not hold, worded the same for every list. */
+function notListedError(kind, id) {
+	return /* @__PURE__ */ new Error(`${kind} ${id} not found in the ${kind.toLowerCase()} list.`);
+}
+//#endregion
+export { listedById, notListedError };
+
+//# sourceMappingURL=list.js.map

package/dist/mutator/list.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.js","names":[],"sources":["../../src/mutator/list.ts"],"sourcesContent":["import type { PlTransaction, SignedResourceId } from \"@milaboratories/pl-client\";\nimport { isNullSignedResourceId, resourceIdToString } from \"@milaboratories/pl-client\";\n\n/** One entry of a list resource: the field holding it and the resource that field points at. */\nexport interface ListedEntry {\n  readonly fieldName: string;\n  readonly rid: SignedResourceId;\n}\n\n/** The kinds of list a root keeps, as a not-found message names them. */\nexport type ListedKind = \"Project\" | \"Template\";\n\n/**\n * Every entry of a list resource — the project list or the template list — keyed by the string\n * form of the resource id it points at, which is what a project or template id is.\n *\n * A list field's name is a uuid unrelated to the id of what it holds, so an entry is only ever\n * found by value. Fields that point at nothing yet are left out.\n */\nexport async function listedById(\n  tx: PlTransaction,\n  listRid: SignedResourceId,\n): Promise<Map<string, ListedEntry>> {\n  const data = await tx.getResourceData(listRid, true);\n  const entries = new Map<string, ListedEntry>();\n  for (const f of data.fields) {\n    if (isNullSignedResourceId(f.value)) continue;\n    entries.set(resourceIdToString(f.value), { fieldName: f.name, rid: f.value });\n  }\n  return entries;\n}\n\n/** What is thrown for an id the list does not hold, worded the same for every list. */\nexport function notListedError(kind: ListedKind, id: string): Error {\n  return new Error(`${kind} ${id} not found in the ${kind.toLowerCase()} list.`);\n}\n"],"mappings":";;;;;;;;;AAmBA,eAAsB,WACpB,IACA,SACmC;CACnC,MAAM,OAAO,MAAM,GAAG,gBAAgB,SAAS,IAAI;CACnD,MAAM,0BAAU,IAAI,IAAyB;CAC7C,KAAK,MAAM,KAAK,KAAK,QAAQ;EAC3B,IAAI,uBAAuB,EAAE,KAAK,GAAG;EACrC,QAAQ,IAAI,mBAAmB,EAAE,KAAK,GAAG;GAAE,WAAW,EAAE;GAAM,KAAK,EAAE;EAAM,CAAC;CAC9E;CACA,OAAO;AACT;;AAGA,SAAgB,eAAe,MAAkB,IAAmB;CAClE,uBAAO,IAAI,MAAM,GAAG,KAAK,GAAG,GAAG,oBAAoB,KAAK,YAAY,EAAE,OAAO;AAC/E"}

package/dist/mutator/project.cjs

@@ -936,10 +936,23 @@ var ProjectMutator = class ProjectMutator {
 	}
 	/** Updates project metadata */
 	setMeta(meta) {
-		this.meta = meta;
+		this.meta = (0, _milaboratories_pl_model_middle_layer.normalizeProjectMeta)(meta);
 		this.metaChanged = true;
 		this.updateLastModified();
 	}
+	/**
+	* Updates the metadata fields the caller names, leaving the rest as they are.
+	*
+	* The merge happens against the metadata this mutator loaded inside the very transaction it
+	* writes in, so a rename and a description edit racing each other cannot make one of them
+	* revert the other's field.
+	*/
+	updateMeta(patch) {
+		this.setMeta({
+			...this.meta,
+			...patch
+		});
+	}
 	/** Background maintenance: render pending stagings + GC of Previous fields. */
 	doRefresh() {
 		this.refreshStagings();