@estiva-app/interop 0.76.0 → 0.77.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.
@@ -25,7 +25,21 @@ export interface FileCandidatesOptions {
25
25
  cache?: ProjectionCache;
26
26
  /** When each address was last written or read, in seconds — newer first within a tier. */
27
27
  at?: ReadonlyMap<string, number>;
28
+ /** The types the relay keeps in order (`RelayFileReads.inOrder`): a project of one is picked as its link. */
29
+ inOrder?: readonly string[];
30
+ /** The host Ship serves projects from: a picked project's link is `<it>/project/<d>`. Ship's own unless said, so every app picks the same link. */
31
+ projectOrigin?: string;
28
32
  }
33
+ /** Where Ship serves projects (§13.1, decided 2026-11-03): one link for a project, whichever app picked it. */
34
+ export declare const SHIP_ORIGIN = "https://ship.estiva.app";
35
+ /**
36
+ * How a picked file goes in the text (§13.1): a project whose type the relay
37
+ * keeps in order as Ship's path link with its id and no title, which every
38
+ * app's host answers; anything else as `nostr:naddr…`.
39
+ *
40
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-file-is-named-by-its-id-in-a-capital-and-small-tag.md
41
+ */
42
+ export declare function pickedFileUri(address: string, { inOrder, projectOrigin }?: Pick<FileCandidatesOptions, 'inOrder' | 'projectOrigin'>): string;
29
43
  /**
30
44
  * Rows for resolved files, all in one tier.
31
45
  *
@@ -37,7 +51,7 @@ export interface FileCandidatesOptions {
37
51
  * offerable — unreachable, untitled, or of a kind `[` does not offer — are
38
52
  * left out.
39
53
  */
40
- export declare function fileCandidates(objects: readonly (ForeignObject | null | undefined)[], tier: number, query: QueryFn, { cache, at }?: FileCandidatesOptions): Promise<ReferenceCandidate[]>;
54
+ export declare function fileCandidates(objects: readonly (ForeignObject | null | undefined)[], tier: number, query: QueryFn, { cache, at, inOrder, projectOrigin }?: FileCandidatesOptions): Promise<ReferenceCandidate[]>;
41
55
  export interface SearchFileReferencesOptions extends Omit<FileCandidatesOptions, 'at'> {
42
56
  /** How many roots, and separately how many renames, the relay is asked for. Default 32. */
43
57
  limit?: number;
@@ -1 +1 @@
1
- {"version":3,"file":"references.d.ts","sourceRoot":"","sources":["../src/references.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAML,KAAK,kBAAkB,EACvB,KAAK,aAAa,EACnB,MAAM,0BAA0B,CAAA;AACjC,OAAO,EAIL,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,OAAO,EACb,MAAM,iBAAiB,CAAA;AAMxB;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAKxE,CAAA;AA2BD,MAAM,WAAW,qBAAqB;IACpC,KAAK,CAAC,EAAE,eAAe,CAAA;IACvB,0FAA0F;IAC1F,EAAE,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACjC;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,SAAS,CAAC,aAAa,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,EACtD,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,EACd,EAAE,KAAK,EAAE,EAAE,EAAE,GAAE,qBAA0B,GACxC,OAAO,CAAC,kBAAkB,EAAE,CAAC,CA+B/B;AAED,MAAM,WAAW,2BAA4B,SAAQ,IAAI,CAAC,qBAAqB,EAAE,IAAI,CAAC;IACpF,2FAA2F;IAC3F,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAWD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,EACd,EAAE,KAAU,EAAE,GAAG,OAAO,EAAE,GAAE,2BAAgC,GAC3D,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAqB/B"}
1
+ {"version":3,"file":"references.d.ts","sourceRoot":"","sources":["../src/references.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAML,KAAK,kBAAkB,EACvB,KAAK,aAAa,EACnB,MAAM,0BAA0B,CAAA;AACjC,OAAO,EAIL,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,OAAO,EACb,MAAM,iBAAiB,CAAA;AAOxB;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAKxE,CAAA;AA2BD,MAAM,WAAW,qBAAqB;IACpC,KAAK,CAAC,EAAE,eAAe,CAAA;IACvB,0FAA0F;IAC1F,EAAE,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,6GAA6G;IAC7G,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC3B,mJAAmJ;IACnJ,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,+GAA+G;AAC/G,eAAO,MAAM,WAAW,4BAA4B,CAAA;AAEpD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,EAAE,OAAY,EAAE,aAA2B,EAAE,GAAE,IAAI,CAAC,qBAAqB,EAAE,SAAS,GAAG,eAAe,CAAM,GAC3G,MAAM,CAGR;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,SAAS,CAAC,aAAa,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,EACtD,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,EACd,EAAE,KAAK,EAAE,EAAE,EAAE,OAAO,EAAE,aAAa,EAAE,GAAE,qBAA0B,GAChE,OAAO,CAAC,kBAAkB,EAAE,CAAC,CA+B/B;AAED,MAAM,WAAW,2BAA4B,SAAQ,IAAI,CAAC,qBAAqB,EAAE,IAAI,CAAC;IACpF,2FAA2F;IAC3F,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAWD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,EACd,EAAE,KAAU,EAAE,GAAG,OAAO,EAAE,GAAE,2BAAgC,GAC3D,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAqB/B"}
@@ -15,6 +15,7 @@
15
15
  */
16
16
  import { FILE_TIER, fileReference, KIND_CHANGE, referenceMatch, refMatch, } from '@estiva-app/conversation';
17
17
  import { isClosedStatus, KIND_BARE_FILE, resolveForeignRoots, } from './projection.js';
18
+ import { fileIdFormOf } from '@estiva-app/protocol';
18
19
  const KIND_PROJECT = 30850;
19
20
  const KIND_ISSUE = 30851;
20
21
  const KIND_DOCUMENT = 30842;
@@ -46,6 +47,19 @@ const offerable = (object) => !!object &&
46
47
  * the `ref` field — so typing it finds the issue. Only an issue has one.
47
48
  */
48
49
  const refOf = (object) => object.kind === KIND_ISSUE ? object.meta.find((slot) => slot.field === 'ref')?.value.trim() || undefined : undefined;
50
+ /** Where Ship serves projects (§13.1, decided 2026-11-03): one link for a project, whichever app picked it. */
51
+ export const SHIP_ORIGIN = 'https://ship.estiva.app';
52
+ /**
53
+ * How a picked file goes in the text (§13.1): a project whose type the relay
54
+ * keeps in order as Ship's path link with its id and no title, which every
55
+ * app's host answers; anything else as `nostr:naddr…`.
56
+ *
57
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-file-is-named-by-its-id-in-a-capital-and-small-tag.md
58
+ */
59
+ export function pickedFileUri(address, { inOrder = [], projectOrigin = SHIP_ORIGIN } = {}) {
60
+ const byId = fileIdFormOf(inOrder, address);
61
+ return byId?.type === 'osnova.project' ? `${projectOrigin.replace(/\/+$/, '')}/project/${byId.id}` : fileReference(address);
62
+ }
49
63
  /**
50
64
  * Rows for resolved files, all in one tier.
51
65
  *
@@ -57,7 +71,7 @@ const refOf = (object) => object.kind === KIND_ISSUE ? object.meta.find((slot) =
57
71
  * offerable — unreachable, untitled, or of a kind `[` does not offer — are
58
72
  * left out.
59
73
  */
60
- export async function fileCandidates(objects, tier, query, { cache, at } = {}) {
74
+ export async function fileCandidates(objects, tier, query, { cache, at, inOrder, projectOrigin } = {}) {
61
75
  const files = objects.filter(offerable);
62
76
  const parents = new Map();
63
77
  for (const o of objects)
@@ -78,7 +92,7 @@ export async function fileCandidates(objects, tier, query, { cache, at } = {}) {
78
92
  const summary = summaryOf(o);
79
93
  return {
80
94
  id: o.address,
81
- uri: fileReference(o.address),
95
+ uri: pickedFileUri(o.address, { inOrder, projectOrigin }),
82
96
  type: typeOf(o.kind),
83
97
  kind: o.kind,
84
98
  title: o.slots.title.value,
@@ -1 +1 @@
1
- {"version":3,"file":"references.js","sourceRoot":"","sources":["../src/references.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EACL,SAAS,EACT,aAAa,EACb,WAAW,EACX,cAAc,EACd,QAAQ,GAGT,MAAM,0BAA0B,CAAA;AACjC,OAAO,EACL,cAAc,EACd,cAAc,EACd,mBAAmB,GAIpB,MAAM,iBAAiB,CAAA;AAExB,MAAM,YAAY,GAAG,KAAK,CAAA;AAC1B,MAAM,UAAU,GAAG,KAAK,CAAA;AACxB,MAAM,aAAa,GAAG,KAAK,CAAA;AAE3B;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAA4C;IAC3E,CAAC,YAAY,CAAC,EAAE,SAAS;IACzB,CAAC,UAAU,CAAC,EAAE,OAAO;IACrB,CAAC,cAAc,CAAC,EAAE,OAAO;IACzB,CAAC,aAAa,CAAC,EAAE,UAAU;CAC5B,CAAA;AAED,gGAAgG;AAChG,MAAM,SAAS,GAAG,CAAC,MAAqB,EAAsB,EAAE;IAC9D,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAA;IAClC,OAAO,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,IAAI,SAAS,CAAC,CAAC,CAAC,SAAS,CAAA;AAC/F,CAAC,CAAA;AAED,MAAM,MAAM,GAAG,CAAC,IAAY,EAA6B,EAAE,CAAC,oBAAoB,CAAC,IAAI,CAAC,CAAA;AAItF,6EAA6E;AAC7E,MAAM,SAAS,GAAG,CAAC,MAAwC,EAAuB,EAAE,CAClF,CAAC,CAAC,MAAM;IACR,CAAC,CAAC,MAAM,CAAC,OAAO;IAChB,CAAC,MAAM,CAAC,WAAW;IACnB,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,SAAS;IACjC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,EAAE,CAAA;AAEpC;;;GAGG;AACH,MAAM,KAAK,GAAG,CAAC,MAAqB,EAAsB,EAAE,CAC1D,MAAM,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,KAAK,KAAK,CAAC,EAAE,KAAK,CAAC,IAAI,EAAE,IAAI,SAAS,CAAC,CAAC,CAAC,SAAS,CAAA;AAQtH;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,OAAsD,EACtD,IAAY,EACZ,KAAc,EACd,EAAE,KAAK,EAAE,EAAE,KAA4B,EAAE;IAEzC,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAA;IACvC,MAAM,OAAO,GAAG,IAAI,GAAG,EAAyB,CAAA;IAChD,KAAK,MAAM,CAAC,IAAI,OAAO;QAAE,IAAI,CAAC,EAAE,OAAO,IAAI,CAAC,CAAC,CAAC,WAAW;YAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAA;IACpF,MAAM,OAAO,GAAG;QACd,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,UAAU,IAAI,CAAC,CAAC,SAAS,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;KAC3H,CAAA;IACD,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QACnB,MAAM,IAAI,GAAG,MAAM,mBAAmB,CAAC,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAA;QAC7E,KAAK,MAAM,MAAM,IAAI,IAAI;YAAE,IAAI,MAAM,CAAC,OAAO;gBAAE,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;IACpF,CAAC;IACD,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QACrB,MAAM,MAAM,GAAG,CAAC,CAAC,IAAI,KAAK,UAAU,IAAI,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;QAC1F,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,CAAA;QACpB,MAAM,OAAO,GAAG,SAAS,CAAC,CAAC,CAAC,CAAA;QAC5B,OAAO;YACL,EAAE,EAAE,CAAC,CAAC,OAAO;YACb,GAAG,EAAE,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC;YAC7B,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,CAAE;YACrB,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,KAAM,CAAC,KAAK;YAC3B,+GAA+G;YAC/G,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC;YACtE,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC/B,IAAI;YACJ,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC/B,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC3D,GAAG,CAAC,CAAC,CAAC,QAAQ,IAAI,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC7D,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACzD,CAAA;IACH,CAAC,CAAC,CAAA;AACJ,CAAC;AAOD,MAAM,KAAK,GAAG,CAAC,KAA2B,EAAE,IAAY,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;AAEvG;;;GAGG;AACH,MAAM,cAAc,GAAG,CAAC,KAAyB,EAAE,OAA2B,EAAE,EAAE,CAChF,KAAK,KAAK,OAAO,IAAI,CAAC,KAAK,KAAK,KAAK,IAAI,OAAO,EAAE,UAAU,CAAC,GAAG,UAAU,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAA;AAEvG;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,IAAY,EACZ,KAAc,EACd,EAAE,KAAK,GAAG,EAAE,EAAE,GAAG,OAAO,KAAkC,EAAE;IAE5D,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,CAAA;IAC1B,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,CAAA;IACtB,MAAM,KAAK,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAA;IAC9D,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC;QACvB,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,GAAG,KAAK,EAAE;QAClE,EAAE,KAAK,EAAE,CAAC,WAAW,CAAC,EAAE,GAAG,KAAK,EAAE;KACnC,CAAC,CAAA;IACF,MAAM,EAAE,GAAG,IAAI,GAAG,EAAkB,CAAA;IACpC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,OAAO,GACX,GAAG,CAAC,IAAI,KAAK,WAAW;YACtB,CAAC,CAAC,cAAc,CAAC,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,EAAE,KAAK,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;YACtD,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,MAAM,IAAI,KAAK,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,EAAE,EAAE,CAAA;QAC9E,IAAI,CAAC,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAAE,SAAQ;QAChE,EAAE,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,UAAU,CAAC,CAAC,CAAA;IACjE,CAAC;IACD,IAAI,EAAE,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,EAAE,CAAA;IAC5B,MAAM,OAAO,GAAG,MAAM,mBAAmB,CAAC,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC,CAAA;IAC/E,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,IAAI,cAAc,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAA;IAC5I,OAAO,cAAc,CAAC,QAAQ,EAAE,SAAS,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,GAAG,OAAO,EAAE,EAAE,EAAE,CAAC,CAAA;AAC9E,CAAC"}
1
+ {"version":3,"file":"references.js","sourceRoot":"","sources":["../src/references.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EACL,SAAS,EACT,aAAa,EACb,WAAW,EACX,cAAc,EACd,QAAQ,GAGT,MAAM,0BAA0B,CAAA;AACjC,OAAO,EACL,cAAc,EACd,cAAc,EACd,mBAAmB,GAIpB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAEnD,MAAM,YAAY,GAAG,KAAK,CAAA;AAC1B,MAAM,UAAU,GAAG,KAAK,CAAA;AACxB,MAAM,aAAa,GAAG,KAAK,CAAA;AAE3B;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAA4C;IAC3E,CAAC,YAAY,CAAC,EAAE,SAAS;IACzB,CAAC,UAAU,CAAC,EAAE,OAAO;IACrB,CAAC,cAAc,CAAC,EAAE,OAAO;IACzB,CAAC,aAAa,CAAC,EAAE,UAAU;CAC5B,CAAA;AAED,gGAAgG;AAChG,MAAM,SAAS,GAAG,CAAC,MAAqB,EAAsB,EAAE;IAC9D,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAA;IAClC,OAAO,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,IAAI,SAAS,CAAC,CAAC,CAAC,SAAS,CAAA;AAC/F,CAAC,CAAA;AAED,MAAM,MAAM,GAAG,CAAC,IAAY,EAA6B,EAAE,CAAC,oBAAoB,CAAC,IAAI,CAAC,CAAA;AAItF,6EAA6E;AAC7E,MAAM,SAAS,GAAG,CAAC,MAAwC,EAAuB,EAAE,CAClF,CAAC,CAAC,MAAM;IACR,CAAC,CAAC,MAAM,CAAC,OAAO;IAChB,CAAC,MAAM,CAAC,WAAW;IACnB,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,SAAS;IACjC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,EAAE,CAAA;AAEpC;;;GAGG;AACH,MAAM,KAAK,GAAG,CAAC,MAAqB,EAAsB,EAAE,CAC1D,MAAM,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,KAAK,KAAK,CAAC,EAAE,KAAK,CAAC,IAAI,EAAE,IAAI,SAAS,CAAC,CAAC,CAAC,SAAS,CAAA;AAYtH,+GAA+G;AAC/G,MAAM,CAAC,MAAM,WAAW,GAAG,yBAAyB,CAAA;AAEpD;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAC3B,OAAe,EACf,EAAE,OAAO,GAAG,EAAE,EAAE,aAAa,GAAG,WAAW,KAA+D,EAAE;IAE5G,MAAM,IAAI,GAAG,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;IAC3C,OAAO,IAAI,EAAE,IAAI,KAAK,gBAAgB,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,YAAY,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,OAAO,CAAC,CAAA;AAC7H,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,OAAsD,EACtD,IAAY,EACZ,KAAc,EACd,EAAE,KAAK,EAAE,EAAE,EAAE,OAAO,EAAE,aAAa,KAA4B,EAAE;IAEjE,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAA;IACvC,MAAM,OAAO,GAAG,IAAI,GAAG,EAAyB,CAAA;IAChD,KAAK,MAAM,CAAC,IAAI,OAAO;QAAE,IAAI,CAAC,EAAE,OAAO,IAAI,CAAC,CAAC,CAAC,WAAW;YAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAA;IACpF,MAAM,OAAO,GAAG;QACd,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,UAAU,IAAI,CAAC,CAAC,SAAS,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;KAC3H,CAAA;IACD,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QACnB,MAAM,IAAI,GAAG,MAAM,mBAAmB,CAAC,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAA;QAC7E,KAAK,MAAM,MAAM,IAAI,IAAI;YAAE,IAAI,MAAM,CAAC,OAAO;gBAAE,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;IACpF,CAAC;IACD,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QACrB,MAAM,MAAM,GAAG,CAAC,CAAC,IAAI,KAAK,UAAU,IAAI,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;QAC1F,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,CAAA;QACpB,MAAM,OAAO,GAAG,SAAS,CAAC,CAAC,CAAC,CAAA;QAC5B,OAAO;YACL,EAAE,EAAE,CAAC,CAAC,OAAO;YACb,GAAG,EAAE,aAAa,CAAC,CAAC,CAAC,OAAO,EAAE,EAAE,OAAO,EAAE,aAAa,EAAE,CAAC;YACzD,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,CAAE;YACrB,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,KAAM,CAAC,KAAK;YAC3B,+GAA+G;YAC/G,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC;YACtE,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC/B,IAAI;YACJ,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC/B,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC3D,GAAG,CAAC,CAAC,CAAC,QAAQ,IAAI,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC7D,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACzD,CAAA;IACH,CAAC,CAAC,CAAA;AACJ,CAAC;AAOD,MAAM,KAAK,GAAG,CAAC,KAA2B,EAAE,IAAY,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;AAEvG;;;GAGG;AACH,MAAM,cAAc,GAAG,CAAC,KAAyB,EAAE,OAA2B,EAAE,EAAE,CAChF,KAAK,KAAK,OAAO,IAAI,CAAC,KAAK,KAAK,KAAK,IAAI,OAAO,EAAE,UAAU,CAAC,GAAG,UAAU,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAA;AAEvG;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,IAAY,EACZ,KAAc,EACd,EAAE,KAAK,GAAG,EAAE,EAAE,GAAG,OAAO,KAAkC,EAAE;IAE5D,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,CAAA;IAC1B,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,CAAA;IACtB,MAAM,KAAK,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAA;IAC9D,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC;QACvB,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,GAAG,KAAK,EAAE;QAClE,EAAE,KAAK,EAAE,CAAC,WAAW,CAAC,EAAE,GAAG,KAAK,EAAE;KACnC,CAAC,CAAA;IACF,MAAM,EAAE,GAAG,IAAI,GAAG,EAAkB,CAAA;IACpC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,OAAO,GACX,GAAG,CAAC,IAAI,KAAK,WAAW;YACtB,CAAC,CAAC,cAAc,CAAC,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,EAAE,KAAK,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;YACtD,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,MAAM,IAAI,KAAK,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,EAAE,EAAE,CAAA;QAC9E,IAAI,CAAC,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAAE,SAAQ;QAChE,EAAE,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,UAAU,CAAC,CAAC,CAAA;IACjE,CAAC;IACD,IAAI,EAAE,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,EAAE,CAAA;IAC5B,MAAM,OAAO,GAAG,MAAM,mBAAmB,CAAC,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC,CAAA;IAC/E,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,IAAI,cAAc,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAA;IAC5I,OAAO,cAAc,CAAC,QAAQ,EAAE,SAAS,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,GAAG,OAAO,EAAE,EAAE,EAAE,CAAC,CAAA;AAC9E,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@estiva-app/interop",
3
- "version": "0.76.0",
3
+ "version": "0.77.0",
4
4
  "description": "Render and act on another app's objects from its published NIP-89 manifest. The owner defines the projection; the consumer decides how it looks.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -47,12 +47,12 @@
47
47
  "prepublishOnly": "npm run build"
48
48
  },
49
49
  "peerDependencies": {
50
- "@estiva-app/conversation": ">=0.26.0",
51
- "@estiva-app/protocol": ">=0.50.0"
50
+ "@estiva-app/conversation": ">=0.27.0",
51
+ "@estiva-app/protocol": ">=0.51.0"
52
52
  },
53
53
  "devDependencies": {
54
- "@estiva-app/conversation": ">=0.26.0",
55
- "@estiva-app/protocol": ">=0.50.0",
54
+ "@estiva-app/conversation": ">=0.27.0",
55
+ "@estiva-app/protocol": ">=0.51.0",
56
56
  "typescript": "~5.9.3"
57
57
  }
58
58
  }
package/src/fields.ts CHANGED
@@ -23,6 +23,7 @@
23
23
  * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/merging-two-changes-to-one-text-never-loses-words.md
24
24
  */
25
25
  import {
26
+ BASE_TYPE_OF_KIND,
26
27
  CONTENT_FORMAT_TAG,
27
28
  mergeTexts,
28
29
  type MergeAsk,
@@ -344,3 +345,173 @@ export async function writeChange(args: WriteChangeArgs): Promise<WriteChangeRes
344
345
  }
345
346
  return { ok: false, refused: `still refused after ${tries} tries: ${last}` }
346
347
  }
348
+
349
+ /** The tags of a one-field change that belong to its field, and so go after the `set` tags. */
350
+ const FIELD_OWN = new Set(['a', 'O', 'field', 'value', 'h', 'ts', 'prev', 'stage', CONTENT_FORMAT_TAG])
351
+
352
+ /** §6.2's order for the tags after the `set` tags; anything else after them. */
353
+ const AFTER_SETS = ['A', 'o', 'imeta', 'p']
354
+ const afterSetsRank = (name: string) => (AFTER_SETS.indexOf(name) + AFTER_SETS.length + 1) % (AFTER_SETS.length + 1)
355
+
356
+ /**
357
+ * One change setting several fields of one file (§6.2), from the one-field
358
+ * changes for each — `buildActionEvent`'s, each with its `prev`, so the
359
+ * manifest has checked every value and staged every status. Tag order: `a`,
360
+ * `O`, `h`, `ts`, one `["set", field, value, prev]` per field, then the
361
+ * text's `content-format`, any other tag once (`A`, `o`, `imeta`, `p`), then
362
+ * one `stage` per staged field. The relay takes it whole or refuses it whole.
363
+ *
364
+ * A string when they are not one file's changes in one Folder, when one sets
365
+ * no field or follows no change, when a field is named twice, or when the
366
+ * file has no id for the `O` a several-field change must carry.
367
+ *
368
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/one-change-may-set-several-fields-taken-whole-or-refused-whole.md
369
+ */
370
+ export function combineChanges(changes: readonly UnsignedEvent[]): UnsignedEvent | string {
371
+ const [first] = changes
372
+ if (!first) return 'A change sets at least one field.'
373
+ const file = tagValue(first, 'a')
374
+ const id = tagValue(first, 'O')
375
+ const folder = tagValue(first, 'h')
376
+ if (!file || !folder) return 'A change names its file and its Folder.'
377
+ if (!id) return `${file} has no id, and a change setting several fields names its file by it.`
378
+ const sets: string[][] = []
379
+ const rest: string[][] = []
380
+ const stages: string[][] = []
381
+ let format: string[] | undefined
382
+ let ms = 0
383
+ for (const change of changes) {
384
+ if (change.kind !== KIND_CHANGE || tagValue(change, 'a') !== file || tagValue(change, 'O') !== id || tagValue(change, 'h') !== folder) {
385
+ return 'A change setting several fields sets them on one file, in its Folder.'
386
+ }
387
+ const field = tagValue(change, 'field')
388
+ const prev = tagValue(change, 'prev')
389
+ if (!field || !prev) return 'Each field of a several-field change names the change it follows.'
390
+ // Who is on a file is kept beside it, never in a `set` (§6.2, §11.8): the relay refuses one.
391
+ if (field.startsWith('member:') || field.startsWith('follow:')) return `${field} is never in a change setting several fields.`
392
+ if (sets.some((s) => s[1] === field)) return `A change names ${field} once.`
393
+ sets.push(['set', field, tagValue(change, 'value') ?? '', prev])
394
+ for (const tag of change.tags) {
395
+ if (tag[0] === 'stage') stages.push([...tag])
396
+ else if (tag[0] === CONTENT_FORMAT_TAG && field === TEXT_FIELD) format = [...tag]
397
+ else if (!FIELD_OWN.has(tag[0]) && !rest.some((t) => t.length === tag.length && t.every((v, i) => v === tag[i]))) rest.push([...tag])
398
+ }
399
+ ms = Math.max(ms, Number(tagValue(change, 'ts')) || change.created_at * 1000)
400
+ }
401
+ return {
402
+ pubkey: first.pubkey,
403
+ created_at: Math.floor(ms / 1000),
404
+ kind: KIND_CHANGE,
405
+ tags: [
406
+ ['a', file],
407
+ ['O', id],
408
+ ['h', folder],
409
+ ['ts', String(ms)],
410
+ ...sets,
411
+ ...(format ? [format] : []),
412
+ ...rest.sort((x, y) => afterSetsRank(x[0]) - afterSetsRank(y[0])),
413
+ ...stages,
414
+ ],
415
+ content: first.content,
416
+ }
417
+ }
418
+
419
+ /** One field of a several-field change, as {@link writeChanges} is handed it. */
420
+ export interface FieldWrite {
421
+ field: string
422
+ value: string
423
+ format?: string
424
+ /** As {@link WriteChangeArgs.prev}: this field's current change as the writer read it. */
425
+ prev: string
426
+ }
427
+
428
+ /** What {@link writeChanges} is handed: {@link WriteChangeArgs}, for several fields of one file. */
429
+ export interface WriteChangesArgs extends Omit<WriteChangeArgs, 'field' | 'value' | 'format' | 'prev' | 'build'> {
430
+ fields: readonly FieldWrite[]
431
+ /**
432
+ * The types the relay keeps in order (`RelayFileReads.inOrder`). A change
433
+ * setting several fields is sent only for one of them: a reader older than
434
+ * interop 0.76.0 folds nothing from a `set`, and the switch is what says
435
+ * every app reads it (record one-change-may-set-several-fields…).
436
+ */
437
+ inOrder: readonly string[]
438
+ /** The unsigned one-field change for one field: `buildActionEvent` bound to that field's action. */
439
+ build: (input: FieldWrite & { createdAtMs: number }) => UnsignedEvent | string
440
+ }
441
+
442
+ /**
443
+ * Write several fields of one file as one change, and answer a `conflict:` as
444
+ * §6.2 says for one: read every field's current change, set again each field
445
+ * other than the text that someone changed since, merge the text by §13.3,
446
+ * and send them again as one change. A text that asks stops it, and nothing is
447
+ * saved; a text whose merge says nothing theirs does not is left out of the
448
+ * change. Each attempt is landed whole or refused whole by the relay.
449
+ */
450
+ export async function writeChanges(args: WriteChangesArgs): Promise<WriteChangeResult> {
451
+ const now = args.now ?? Date.now
452
+ const tries = args.tries ?? 4
453
+ let fields = args.fields.map((f) => ({ ...f, base: undefined as MergeText | undefined }))
454
+ let after = 0
455
+ let mergedOnto: SignedEvent | undefined
456
+ let last = ''
457
+
458
+ for (let attempt = 0; attempt < tries; attempt++) {
459
+ const createdAtMs = Math.max(now(), after)
460
+ const built: UnsignedEvent[] = []
461
+ for (const f of fields) {
462
+ const one = args.build({ field: f.field, value: f.value, ...(f.format ? { format: f.format } : {}), prev: f.prev, createdAtMs })
463
+ if (typeof one === 'string') return { ok: false, refused: one }
464
+ built.push(one)
465
+ }
466
+ const change = combineChanges(built)
467
+ if (typeof change === 'string') return { ok: false, refused: change }
468
+ const type = BASE_TYPE_OF_KIND[change.tags[0][1].split(':').map(Number)[0]]
469
+ if (!type || !args.inOrder.includes(type)) {
470
+ return { ok: false, refused: 'Several fields go in one change only once the relay keeps this type in order: write each with writeChange.' }
471
+ }
472
+ const signed = await args.sign(change)
473
+ const answer = await args.publish(signed)
474
+ if (answer.ok) return { ok: true, id: answer.eventId ?? signed.id, event: signed, ...(mergedOnto ? { mergedOnto } : {}) }
475
+ last = answer.reason ?? 'refused with no reason'
476
+ const conflict = conflictOf(last)
477
+ if (!conflict || conflict.kind === 'other' || !fields.some((f) => f.field === conflict.field)) return { ok: false, refused: last }
478
+
479
+ if (conflict.kind === 'sorts-before') {
480
+ // After every field's prev, not only the one named: the next field would be refused the same way.
481
+ const followed = await Promise.all(fields.map((f) => byId(args.query, f.prev)))
482
+ if (followed.some((e) => !e)) return { ok: false, refused: last }
483
+ after = Math.max(...followed.map((e) => changedAt(e!) + 1))
484
+ continue
485
+ }
486
+
487
+ const heads = await Promise.all(
488
+ fields.map((f) => (f.field === conflict.field && conflict.current ? byId(args.query, conflict.current) : args.current(f.field))),
489
+ )
490
+ const next: typeof fields = []
491
+ for (const [i, f] of fields.entries()) {
492
+ const head = heads[i]
493
+ if (!head) return { ok: false, refused: last }
494
+ after = Math.max(after, changedAt(head) + 1)
495
+ if (head.id === f.prev) {
496
+ next.push(f)
497
+ continue
498
+ }
499
+ if (f.field !== TEXT_FIELD) {
500
+ next.push({ ...f, prev: head.id })
501
+ continue
502
+ }
503
+ const base = f.base ?? (await byId(args.query, f.prev).then((e) => e && textOf(e)))
504
+ if (!base) return { ok: false, refused: `${last} (the text it followed, ${f.prev}, could not be read to merge onto)` }
505
+ const theirs = textOf(head)
506
+ if (!theirs) return { ok: false, refused: last }
507
+ const merge = mergeTexts(base, theirs, { value: f.value, ...(f.format ? { format: f.format } : {}) })
508
+ if (merge.asks) return { ok: false, asks: merge.asks, theirs: head }
509
+ mergedOnto = head
510
+ if (merge.merged.value === theirs.value && (merge.merged.format ?? '') === (theirs.format ?? '')) continue
511
+ next.push({ field: f.field, value: merge.merged.value, ...(merge.merged.format ? { format: merge.merged.format } : {}), prev: head.id, base: theirs })
512
+ }
513
+ if (!next.length) return { ok: true, unchanged: true, id: mergedOnto!.id, mergedOnto: mergedOnto! }
514
+ fields = next
515
+ }
516
+ return { ok: false, refused: `still refused after ${tries} tries: ${last}` }
517
+ }
package/src/folders.ts CHANGED
@@ -50,6 +50,7 @@ import {
50
50
  buildDeleteChannel,
51
51
  buildEditChannelMetadata,
52
52
  buildFolderCommand,
53
+ fileIdFormOf,
53
54
  isFileId,
54
55
  KIND,
55
56
  type ChannelVisibility,
@@ -158,10 +159,19 @@ export function planDeleteFolder(pubkey: string, createdAtMs: number, args: { fo
158
159
  export function planPlaceFile(
159
160
  pubkey: string,
160
161
  createdAtMs: number,
161
- args: { folder: string; address: string; hasState: boolean },
162
+ args: { folder: string; address: string; hasState: boolean; inOrder?: readonly string[] },
162
163
  ): UnsignedEvent[] {
163
164
  if (!args.hasState) return []
164
- return [buildFolderCommand(pubkey, createdAtMs, { folder: args.folder, op: 'add', addresses: [args.address] })]
165
+ return [buildFolderCommand(pubkey, createdAtMs, { folder: args.folder, op: 'add', addresses: [listedAs(args.address, args.inOrder)] })]
166
+ }
167
+
168
+ /**
169
+ * How a command names a file: by its id once the relay keeps its type in
170
+ * order (`RelayFileReads.inOrder`, §3.3 "lists by `o` once every app reading
171
+ * the Folder reads both"), else by its address.
172
+ */
173
+ function listedAs(address: string, inOrder: readonly string[] = []): string {
174
+ return fileIdFormOf(inOrder, address)?.id ?? address
165
175
  }
166
176
 
167
177
  /**
@@ -177,10 +187,10 @@ export function planPlaceFile(
177
187
  export function planUnlistFile(
178
188
  pubkey: string,
179
189
  createdAtMs: number,
180
- args: { folder: string; address: string; hasState: boolean },
190
+ args: { folder: string; address: string; hasState: boolean; inOrder?: readonly string[] },
181
191
  ): UnsignedEvent[] {
182
192
  if (!args.hasState) return []
183
- return [buildFolderCommand(pubkey, createdAtMs, { folder: args.folder, op: 'remove', addresses: [args.address] })]
193
+ return [buildFolderCommand(pubkey, createdAtMs, { folder: args.folder, op: 'remove', addresses: [listedAs(args.address, args.inOrder)] })]
184
194
  }
185
195
 
186
196
  /**
package/src/index.ts CHANGED
@@ -118,6 +118,8 @@ export { createLoadQuery, type LoadQueryOptions } from './loadQuery.js'
118
118
  */
119
119
  export {
120
120
  fileCandidates,
121
+ pickedFileUri,
122
+ SHIP_ORIGIN,
121
123
  REFERENCE_FILE_TYPES,
122
124
  searchFileReferences,
123
125
  type FileCandidatesOptions,
@@ -189,11 +191,15 @@ export {
189
191
  openFile,
190
192
  textOf,
191
193
  conflictOf,
194
+ combineChanges,
192
195
  writeChange,
196
+ writeChanges,
193
197
  type CurrentField,
194
198
  type FileFields,
195
199
  type Conflict,
200
+ type FieldWrite,
196
201
  type WriteChangeArgs,
202
+ type WriteChangesArgs,
197
203
  type WriteChangeResult,
198
204
  } from './fields.js'
199
205
 
package/src/links.ts CHANGED
@@ -24,7 +24,7 @@
24
24
  * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/an-edit-says-what-the-message-links-now.md
25
25
  */
26
26
  import { MAX_PARTS } from '@estiva-app/conversation'
27
- import { partTag, valuesIn, type LinkResolver, type PartPointer, type RenderBlock } from '@estiva-app/protocol'
27
+ import { fileIdFormOf, partTag, valuesIn, type LinkResolver, type PartPointer, type RenderBlock } from '@estiva-app/protocol'
28
28
  import { matchObjectUrl, urlPatternsOf, type UrlPattern } from './objectUrl.js'
29
29
  import type { QueryFn } from './projection.js'
30
30
 
@@ -79,7 +79,11 @@ export interface LinkReader {
79
79
  * first what its links name and waiting at most `waitMs` (default 5 s): a
80
80
  * link not answered by then earns nothing, and the body keeps it.
81
81
  */
82
- tagsFor(blocks: readonly RenderBlock[], own: OwnPlace, options?: { waitMs?: number; edit?: boolean }): Promise<string[][]>
82
+ tagsFor(
83
+ blocks: readonly RenderBlock[],
84
+ own: OwnPlace,
85
+ options?: { waitMs?: number; edit?: boolean; inOrder?: readonly string[] },
86
+ ): Promise<string[][]>
83
87
  /** {@link writtenOpenerOf} against the hosts the manifests read so far declare. */
84
88
  opener(url: string | undefined, opens: string | undefined, origin: string): string | undefined
85
89
  /** Every host an app declares its paths on, as the manifests read so far said. */
@@ -217,13 +221,13 @@ export function linkReader(options: LinkReaderOptions): LinkReader {
217
221
  }
218
222
  },
219
223
  version: () => answered,
220
- async tagsFor(blocks, own, { waitMs = 5000, edit = false } = {}) {
224
+ async tagsFor(blocks, own, { waitMs = 5000, edit = false, inOrder = [] } = {}) {
221
225
  const urls = linksIn(blocks).slice(0, MAX_LINKS_ASKED)
222
226
  const waiting = urls.filter((url) => !known.has(url))
223
227
  if (waiting.length > 0) await within(Promise.allSettled(waiting.map(answerOf)), waitMs)
224
228
  const first = new Set(urls)
225
229
  const resolve: LinkResolver = (url) => (first.has(url) ? knownValue(url) : undefined)
226
- return linkTagsOf(blocks, own, resolve, edit ? undefined : (url) => (first.has(url) ? knownBlock(url) : undefined))
230
+ return linkTagsOf(blocks, own, resolve, edit ? undefined : (url) => (first.has(url) ? knownBlock(url) : undefined), inOrder)
227
231
  },
228
232
  opener: (url, opens, origin) => writtenOpenerOf(url, opens, origin, origins),
229
233
  declaredOrigins: () => origins,
@@ -256,13 +260,19 @@ export function linksIn(blocks: readonly RenderBlock[]): string[] {
256
260
  * message links now. An edit carries no `part` (pass no `blockOf`), and a
257
261
  * person is never here: `p` and `urgent` stay as the send wrote them.
258
262
  *
263
+ * A file whose type the relay keeps in order (`inOrder`) is named by its id
264
+ * too: an `o` after its `a`, and its `part` by the id (§6.4, §13.6.1). An
265
+ * edit carries the `o` as a send does (§6.8).
266
+ *
259
267
  * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/an-edit-says-what-the-message-links-now.md
268
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-file-is-named-by-its-id-in-a-capital-and-small-tag.md
260
269
  */
261
270
  export function linkTagsOf(
262
271
  blocks: readonly RenderBlock[],
263
272
  own: OwnPlace,
264
273
  resolve: LinkResolver,
265
274
  blockOf?: (url: string) => PartPointer | undefined,
275
+ inOrder: readonly string[] = [],
266
276
  ): string[][] {
267
277
  const file = own.file && sameValue(own.file)
268
278
  const parent = own.parent?.toLowerCase()
@@ -270,7 +280,11 @@ export function linkTagsOf(
270
280
  for (const value of valuesIn(blocks, resolve)) {
271
281
  if (EVENT_ID.test(value)) {
272
282
  if (value !== parent) tags.push(['q', value])
273
- } else if (value !== file) tags.push(['a', value])
283
+ } else if (value !== file) {
284
+ tags.push(['a', value])
285
+ const byId = fileIdFormOf(inOrder, value)
286
+ if (byId && !tags.some((t) => t[0] === 'o' && t[1] === byId.id)) tags.push(['o', byId.id])
287
+ }
274
288
  }
275
289
  if (blockOf) {
276
290
  const parts = new Map<string, string>()
@@ -279,7 +293,7 @@ export function linkTagsOf(
279
293
  if (part && sameValue(part.address) !== file && !parts.has(part.address)) parts.set(part.address, part.block)
280
294
  }
281
295
  // As many as a box shows under it (conversation's `boxLinksOf`): a part the box did not draw is not sent.
282
- for (const [address, block] of [...parts].slice(0, MAX_PARTS)) tags.push(partTag(address, block))
296
+ for (const [address, block] of [...parts].slice(0, MAX_PARTS)) tags.push(partTag(fileIdFormOf(inOrder, address)?.id ?? address, block))
283
297
  }
284
298
  return tags
285
299
  }
package/src/projection.ts CHANGED
@@ -14,7 +14,7 @@
14
14
  */
15
15
  import { decodeNevent, encodeNaddr, encodeNevent, pointerToAddress, referenceToPointer, type AddressPointer, type EventPointer } from '@estiva-app/protocol'
16
16
  import { parseProfile, type Profile, type SignedEvent } from '@estiva-app/protocol'
17
- import { FILE_KINDS, MAX_FILTERS_PER_QUERY, RELAY_PAGE_CEILING } from '@estiva-app/protocol'
17
+ import { FILE_KINDS, MAX_FILTERS_PER_QUERY, RELAY_PAGE_CEILING, fileIdFormOf } from '@estiva-app/protocol'
18
18
  import {
19
19
  attachmentsInDocument,
20
20
  BLOCK_DOCUMENT_FORMAT,
@@ -228,7 +228,7 @@ export const KIND_MESSAGE = 9
228
228
  const KIND_DELETION = 5
229
229
 
230
230
  /** The tags a comment's body earns for what it names: `ActionEventArgs.linkTags`. */
231
- const LINK_TAG_NAMES = new Set(['a', 'q', 'part'])
231
+ const LINK_TAG_NAMES = new Set(['a', 'o', 'q', 'part'])
232
232
 
233
233
  /**
234
234
  * Every kind an app's comments might be under — what it publishes **now**, plus
@@ -5933,6 +5933,13 @@ export interface ActionEventArgs {
5933
5933
  * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-file-is-its-fields-each-kept-in-order-by-the-relay.md
5934
5934
  */
5935
5935
  prev?: string
5936
+ /**
5937
+ * The types the relay keeps in order (`RelayFileReads.inOrder`): a comment
5938
+ * on a file of one names it by its id too, and a Folder command lists it by
5939
+ * its id (SPEC §6.4, "Apps move to the pair type by type"). Absent, by its
5940
+ * address alone, as every reader reads it.
5941
+ */
5942
+ inOrder?: readonly string[]
5936
5943
  pubkey: string
5937
5944
  createdAtMs: number
5938
5945
  }
@@ -5993,7 +6000,7 @@ export function buildActionEvents(
5993
6000
  return [
5994
6001
  first,
5995
6002
  ...folders.flatMap((listing) =>
5996
- planUnlistFile(args.pubkey, args.createdAtMs, { folder: listing.id, address: args.address, hasState: listing.hasState }),
6003
+ planUnlistFile(args.pubkey, args.createdAtMs, { folder: listing.id, address: args.address, hasState: listing.hasState, inOrder: args.inOrder }),
5997
6004
  ),
5998
6005
  ]
5999
6006
  }
@@ -6007,7 +6014,7 @@ export function buildActionEvents(
6007
6014
  return `"${declared.label}" lists what it creates, and a kind ${first.kind} has no address to list.`
6008
6015
  }
6009
6016
  const created = pointerToAddress({ kind: first.kind, pubkey: first.pubkey, identifier, relays: [] })
6010
- return [first, ...planPlaceFile(args.pubkey, args.createdAtMs, { folder: args.folder, address: created, hasState: args.folderHasState })]
6017
+ return [first, ...planPlaceFile(args.pubkey, args.createdAtMs, { folder: args.folder, address: created, hasState: args.folderHasState, inOrder: args.inOrder })]
6011
6018
  }
6012
6019
  // A change or a comment adds nothing to a Folder and removes nothing from it.
6013
6020
  return [first]
@@ -6136,6 +6143,8 @@ function buildOneActionEvent(args: ActionEventArgs): UnsignedActionEvent | strin
6136
6143
  // The file the change is about, by its id, beside its address (§6.2): the
6137
6144
  // relay keeps each field in order by it.
6138
6145
  const fileId = records.targetTag === 'a' ? identifierOf(address) : undefined
6146
+ // A comment names its file by its id too once its type is kept in order (§6.4, "A comment in both forms").
6147
+ const byId = fileIdFormOf(args.inOrder ?? [], address)
6139
6148
  const tags: string[][] = declared.emits.field
6140
6149
  ? [
6141
6150
  [records.targetTag, address],
@@ -6154,6 +6163,7 @@ function buildOneActionEvent(args: ActionEventArgs): UnsignedActionEvent | strin
6154
6163
  ['A', address],
6155
6164
  ['K', String(kind)],
6156
6165
  ['P', args.objectAuthor],
6166
+ ...(byId ? [['O', byId.id], ['K', byId.type]] : []),
6157
6167
  ...(replyTo
6158
6168
  ? [
6159
6169
  ['e', replyTo.id],
@@ -6169,6 +6179,7 @@ function buildOneActionEvent(args: ActionEventArgs): UnsignedActionEvent | strin
6169
6179
  : [
6170
6180
  ['a', address],
6171
6181
  ['k', String(kind)],
6182
+ ...(byId ? [['o', byId.id], ['k', byId.type]] : []),
6172
6183
  ['p', args.objectAuthor],
6173
6184
  ]),
6174
6185
  ['h', folder],
@@ -6202,6 +6213,8 @@ function buildOneActionEvent(args: ActionEventArgs): UnsignedActionEvent | strin
6202
6213
  for (const tag of args.linkTags ?? []) {
6203
6214
  if (!LINK_TAG_NAMES.has(tag[0]) || typeof tag[1] !== 'string') continue
6204
6215
  if ((tag[0] === 'a' || tag[0] === 'part') && tag[1] === address) continue
6216
+ // The comment's own file by its id is its `o`/`O` already, never a link.
6217
+ if ((tag[0] === 'o' || tag[0] === 'part') && fileId !== undefined && tag[1] === fileId) continue
6205
6218
  if (tag[0] === 'q' && tag[1] === replyTo?.id) continue
6206
6219
  if (!tags.some((t) => t[0] === tag[0] && t[1] === tag[1])) tags.push([...tag])
6207
6220
  }
package/src/references.ts CHANGED
@@ -30,6 +30,7 @@ import {
30
30
  type ProjectionCache,
31
31
  type QueryFn,
32
32
  } from './projection.js'
33
+ import { fileIdFormOf } from '@estiva-app/protocol'
33
34
 
34
35
  const KIND_PROJECT = 30850
35
36
  const KIND_ISSUE = 30851
@@ -76,6 +77,28 @@ export interface FileCandidatesOptions {
76
77
  cache?: ProjectionCache
77
78
  /** When each address was last written or read, in seconds — newer first within a tier. */
78
79
  at?: ReadonlyMap<string, number>
80
+ /** The types the relay keeps in order (`RelayFileReads.inOrder`): a project of one is picked as its link. */
81
+ inOrder?: readonly string[]
82
+ /** The host Ship serves projects from: a picked project's link is `<it>/project/<d>`. Ship's own unless said, so every app picks the same link. */
83
+ projectOrigin?: string
84
+ }
85
+
86
+ /** Where Ship serves projects (§13.1, decided 2026-11-03): one link for a project, whichever app picked it. */
87
+ export const SHIP_ORIGIN = 'https://ship.estiva.app'
88
+
89
+ /**
90
+ * How a picked file goes in the text (§13.1): a project whose type the relay
91
+ * keeps in order as Ship's path link with its id and no title, which every
92
+ * app's host answers; anything else as `nostr:naddr…`.
93
+ *
94
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-file-is-named-by-its-id-in-a-capital-and-small-tag.md
95
+ */
96
+ export function pickedFileUri(
97
+ address: string,
98
+ { inOrder = [], projectOrigin = SHIP_ORIGIN }: Pick<FileCandidatesOptions, 'inOrder' | 'projectOrigin'> = {},
99
+ ): string {
100
+ const byId = fileIdFormOf(inOrder, address)
101
+ return byId?.type === 'osnova.project' ? `${projectOrigin.replace(/\/+$/, '')}/project/${byId.id}` : fileReference(address)
79
102
  }
80
103
 
81
104
  /**
@@ -93,7 +116,7 @@ export async function fileCandidates(
93
116
  objects: readonly (ForeignObject | null | undefined)[],
94
117
  tier: number,
95
118
  query: QueryFn,
96
- { cache, at }: FileCandidatesOptions = {},
119
+ { cache, at, inOrder, projectOrigin }: FileCandidatesOptions = {},
97
120
  ): Promise<ReferenceCandidate[]> {
98
121
  const files = objects.filter(offerable)
99
122
  const parents = new Map<string, ForeignObject>()
@@ -111,7 +134,7 @@ export async function fileCandidates(
111
134
  const summary = summaryOf(o)
112
135
  return {
113
136
  id: o.address,
114
- uri: fileReference(o.address),
137
+ uri: pickedFileUri(o.address, { inOrder, projectOrigin }),
115
138
  type: typeOf(o.kind)!,
116
139
  kind: o.kind,
117
140
  title: o.slots.title!.value,