@estiva-app/interop 0.36.0 → 0.37.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/projection.ts CHANGED
@@ -1483,6 +1483,19 @@ export interface ResolvedManifest {
1483
1483
  */
1484
1484
  export const KIND_BARE_FILE = 30840
1485
1485
 
1486
+ /**
1487
+ * The field that archives a file, whatever its kind — FOL-46.
1488
+ *
1489
+ * **One concept for every file.** A Ship project, a Ship issue, a Peek topic, a
1490
+ * bare file and a Folder are all archived the same way: a change setting
1491
+ * `archived` to `'true'` on the file's address, and an empty value to restore
1492
+ * it. That is the shape Ship has written for projects since SPEC §6.5, so
1493
+ * nothing on the relay needs migrating. It is a change, never a deletion, so it
1494
+ * is reversible, attributed, and open to anyone who may write in the Folder —
1495
+ * not only the author.
1496
+ */
1497
+ export const ARCHIVED_FIELD = 'archived'
1498
+
1486
1499
  /**
1487
1500
  * Where a `ResolvedManifest.address` would name the manifest event, this names
1488
1501
  * the section of the specification the manifest is built from. Not an address,
@@ -1594,6 +1607,23 @@ const BARE_FILE_MANIFEST: Manifest = {
1594
1607
  emits: { kind: 1851, field: 'parent' },
1595
1608
  input: { type: 'string' },
1596
1609
  },
1610
+ /*
1611
+ `archive` is the one field every file may carry (FOL-46): `true` hides the
1612
+ file and everything under it from every list, an empty value brings it
1613
+ back. A change, so anyone in the team may, and the archiving change's
1614
+ `content` is the resolution summary a person gave (`ActionEventArgs.note`).
1615
+ */
1616
+ {
1617
+ id: 'archive',
1618
+ label: 'Archive',
1619
+ description:
1620
+ 'Take this file and everything under it out of every list once nobody needs to see it, or bring it ' +
1621
+ 'back: `true` archives, an empty value restores. Nothing is deleted, and a link still opens it.',
1622
+ effect: 'writes',
1623
+ appliesTo: [String(KIND_BARE_FILE)],
1624
+ emits: { kind: 1851, field: ARCHIVED_FIELD },
1625
+ input: { type: 'string', enum: ARCHIVED_FIELD },
1626
+ },
1597
1627
  {
1598
1628
  id: 'delete',
1599
1629
  label: 'Delete',
@@ -1605,6 +1635,13 @@ const BARE_FILE_MANIFEST: Manifest = {
1605
1635
  emits: { kind: KIND_DELETION },
1606
1636
  },
1607
1637
  ],
1638
+ vocabularies: {
1639
+ // Ship's `ARCHIVED_STATES`, value for value: one field, one vocabulary.
1640
+ [ARCHIVED_FIELD]: [
1641
+ { value: '', label: 'Active', colour: 'neutral' },
1642
+ { value: 'true', label: 'Archived', colour: 'muted' },
1643
+ ],
1644
+ },
1608
1645
  }
1609
1646
 
1610
1647
  function bareFileManifest(): ResolvedManifest {
@@ -2031,6 +2068,112 @@ function foldChanges(changes: SignedEvent[], rule: RecordsRule) {
2031
2068
  return fields
2032
2069
  }
2033
2070
 
2071
+ /**
2072
+ * How an `archived` change is read when the file's kind declares no rule of its
2073
+ * own — a Folder, whose `kind:39000` no app owns, and a bare file. SPEC §7.1's
2074
+ * `kind:1851` shape, the one every Estiva app writes.
2075
+ */
2076
+ const ARCHIVE_RULE: RecordsRule = {
2077
+ changeKind: 1851,
2078
+ targetTag: 'a',
2079
+ fieldTag: 'field',
2080
+ valueTag: 'value',
2081
+ order: ['ts', 'created_at', 'id'],
2082
+ rule: 'last-write-wins-per-field',
2083
+ }
2084
+
2085
+ /** The rule an `archived` change on this file is folded by: its app's, or SPEC's. */
2086
+ function archiveRuleOf(manifest: Pick<Manifest, 'records'> | undefined): RecordsRule {
2087
+ return manifest?.records ?? ARCHIVE_RULE
2088
+ }
2089
+
2090
+ /**
2091
+ * The note Ship wrote on every archive before FOL-46, when the note was the
2092
+ * activity feed's wording rather than anything a person typed. Twelve are on
2093
+ * production (measured 2026-09-29), and none of them is a resolution.
2094
+ */
2095
+ const PLACEHOLDER_ARCHIVE_NOTE = 'archived'
2096
+
2097
+ /** A file that is archived: who did it, when, and what they said about it. */
2098
+ export interface Archive {
2099
+ /** Who wrote the archiving change. */
2100
+ by: string
2101
+ /** Its `created_at`, in seconds. */
2102
+ at: number
2103
+ /**
2104
+ * The resolution summary, when the person archiving gave one — the archiving
2105
+ * change's `content`. One event, so the summary can never land without the
2106
+ * archive or outlive the unarchive that replaces it.
2107
+ */
2108
+ resolution?: string
2109
+ /**
2110
+ * Present when the file is not archived itself but is hidden **with** an
2111
+ * archived ancestor: that ancestor's address — the project an issue belongs
2112
+ * to, the file a sub-topic sits under, the record a channel belongs to.
2113
+ *
2114
+ * Computed when reading and never written to the file (FOL-46): unarchiving
2115
+ * the ancestor restores exactly what was there before, and archiving a
2116
+ * project with two hundred issues is one event rather than two hundred.
2117
+ */
2118
+ with?: string
2119
+ }
2120
+
2121
+ /**
2122
+ * Whether a file — or a Folder — is archived, itself or with an ancestor.
2123
+ *
2124
+ * Reads the {@link Archive} a resolver put on it. A resolver leaves archived
2125
+ * files out of a Folder's contents, so this matters where a file is reached
2126
+ * directly: a link, a mention, a page opened by address.
2127
+ */
2128
+ export function isArchived(file: { archived?: Archive } | null | undefined): boolean {
2129
+ return !!file?.archived
2130
+ }
2131
+
2132
+ /**
2133
+ * The file's archive, if the last `archived` change archived it.
2134
+ *
2135
+ * `changes` may hold any events; only this rule's change kind, naming this
2136
+ * address, setting this field, is read. Last write wins, by the same order as
2137
+ * every other field.
2138
+ */
2139
+ function archiveOf(changes: SignedEvent[], address: string, rule: RecordsRule): Archive | undefined {
2140
+ let last: SignedEvent | undefined
2141
+ for (const change of changes) {
2142
+ // The target is the first target tag, as every other fold reads it: a
2143
+ // change archiving one file must not archive another it also mentions.
2144
+ if (change.kind !== rule.changeKind || tagValue(change, rule.targetTag) !== address) continue
2145
+ if (tagValue(change, rule.fieldTag) !== ARCHIVED_FIELD || tagValue(change, rule.valueTag) === undefined) continue
2146
+ if (!last || byOrder(last, change) < 0) last = change
2147
+ }
2148
+ if (!last || tagValue(last, rule.valueTag) !== 'true') return undefined
2149
+ const note = last.content.trim()
2150
+ return {
2151
+ by: last.pubkey,
2152
+ at: last.created_at,
2153
+ ...(note && note !== PLACEHOLDER_ARCHIVE_NOTE ? { resolution: last.content } : {}),
2154
+ }
2155
+ }
2156
+
2157
+ /**
2158
+ * The first archived ancestor of `address`, walking `parentOf`, with its archive.
2159
+ *
2160
+ * Stops at a cycle rather than looping: `parentRef` is written by people, and
2161
+ * two files each moved under the other is a state the relay accepts.
2162
+ */
2163
+ function archivedAncestorOf(
2164
+ address: string,
2165
+ parentOf: (address: string) => string | undefined,
2166
+ archiveAt: (address: string) => Archive | undefined,
2167
+ ): Archive | undefined {
2168
+ const seen = new Set([address])
2169
+ for (let parent = parentOf(address); parent && !seen.has(parent); parent = parentOf(parent)) {
2170
+ seen.add(parent)
2171
+ const archive = archiveAt(parent)
2172
+ if (archive) return { ...archive, with: archive.with ?? parent }
2173
+ }
2174
+ return undefined
2175
+ }
2176
+
2034
2177
  function truncate(text: string, limit?: number) {
2035
2178
  if (!limit || text.length <= limit) return text
2036
2179
  return `${text.slice(0, limit).trimEnd()}…`
@@ -2679,6 +2822,15 @@ export interface ForeignObject {
2679
2822
  * rendering nothing.
2680
2823
  */
2681
2824
  unreachable?: boolean
2825
+ /**
2826
+ * Present when the file is archived, itself or with an ancestor (FOL-46).
2827
+ *
2828
+ * A Folder's contents leave archived files out, so this is set where a file
2829
+ * is reached by address: its page draws an Archived banner with the
2830
+ * resolution and an Unarchive control rather than drawing it as live work.
2831
+ * See {@link Archive} and {@link isArchived}.
2832
+ */
2833
+ archived?: Archive
2682
2834
  }
2683
2835
 
2684
2836
 
@@ -2697,6 +2849,7 @@ function buildObject(args: {
2697
2849
  viaRecommendation: boolean
2698
2850
  webTemplate?: string
2699
2851
  comments?: ForeignObject['comments']
2852
+ archived?: Archive
2700
2853
  }): ForeignObject {
2701
2854
  const { root, pointer, manifest, projection, folded } = args
2702
2855
  const naddr = encodeNaddr(pointer)
@@ -2748,6 +2901,7 @@ function buildObject(args: {
2748
2901
  : action,
2749
2902
  ),
2750
2903
  viaRecommendation: args.viaRecommendation,
2904
+ ...(args.archived ? { archived: args.archived } : {}),
2751
2905
  }
2752
2906
  }
2753
2907
 
@@ -2855,6 +3009,7 @@ export async function resolveForeignObject(
2855
3009
  * omitting it is exactly the old behaviour.
2856
3010
  */
2857
3011
  cache?: ProjectionCache,
3012
+ options: ArchiveReadOptions = {},
2858
3013
  ): Promise<ForeignObject | null> {
2859
3014
  const pointer = addressPointerOf(naddr)
2860
3015
  if (!pointer) return null
@@ -2865,6 +3020,7 @@ export async function resolveForeignObject(
2865
3020
 
2866
3021
  const assembled = assembleObject(plan, await query(plan.filters))
2867
3022
  if (assembled.object.unreachable) return assembled.object
3023
+ if (options.archivedWith) await markArchivedParents([assembled.object], query)
2868
3024
  return withPeople(assembled, await (lookupPeople ?? peopleViaRelay(query))(peopleOf(assembled)))
2869
3025
  }
2870
3026
 
@@ -2911,6 +3067,7 @@ export async function resolveForeignObjects(
2911
3067
  lookupPeople?: PeopleFn,
2912
3068
  /** See {@link ProjectionCache}. Omitting it still reads each app's manifest once per call. */
2913
3069
  cache?: ProjectionCache,
3070
+ options: ArchiveReadOptions = {},
2914
3071
  ): Promise<Record<string, ForeignObject | null>> {
2915
3072
  const results: Record<string, ForeignObject | null> = {}
2916
3073
  const asked: { reference: string; pointer: AddressPointer }[] = []
@@ -2957,6 +3114,7 @@ export async function resolveForeignObjects(
2957
3114
  const events = (await Promise.all(chunks.map((chunk) => query(chunk)))).flat()
2958
3115
 
2959
3116
  const assembled = plans.map(({ reference, plan }) => ({ reference, built: assembleObject(plan, events) }))
3117
+ if (options.archivedWith) await markArchivedParents(assembled.map(({ built }) => built.object), query)
2960
3118
  const wanted = [...new Set(assembled.flatMap(({ built }) => peopleOf(built)))]
2961
3119
  const reachable = assembled.some(({ built }) => !built.object.unreachable)
2962
3120
  const people = reachable ? await (lookupPeople ?? peopleViaRelay(query))(wanted) : {}
@@ -2975,6 +3133,73 @@ export async function resolveForeignObjects(
2975
3133
  return results
2976
3134
  }
2977
3135
 
3136
+ /** What {@link resolveForeignObject} and {@link resolveForeignObjects} may read beyond the file itself. */
3137
+ export interface ArchiveReadOptions {
3138
+ /**
3139
+ * Also read whether each file's parent is archived, and mark the file
3140
+ * archived **with** it (`archived.with`) — FOL-46. For the page a link opens,
3141
+ * which draws the banner; off by default because it is one more request
3142
+ * whenever a file has a parent, and a refresh tick that resolves an issue
3143
+ * card would pay it every time (SHI-13's one request per tick).
3144
+ */
3145
+ archivedWith?: boolean
3146
+ }
3147
+
3148
+ /**
3149
+ * Mark each object that is hidden with an archived parent — FOL-46.
3150
+ *
3151
+ * An issue whose project is archived is archived with it, and its page says so
3152
+ * rather than drawing live work. The cascade is computed here and never written
3153
+ * to the issue, so unarchiving the project restores it exactly.
3154
+ *
3155
+ * **One read for the whole set, and only when some object has a parent**, so a
3156
+ * topic page or a project page pays nothing. One level: the parent's own
3157
+ * parent is not followed, because the page is about this file and its
3158
+ * container, and a deeper walk is a round trip per level. A Folder listing
3159
+ * walks the whole chain it holds ({@link resolveFolderContents}).
3160
+ *
3161
+ * The parent is folded by SPEC's rule, which every Estiva app writes: the
3162
+ * parent may belong to another app, whose manifest is not in hand.
3163
+ */
3164
+ async function markArchivedParents(objects: ForeignObject[], query: QueryFn): Promise<void> {
3165
+ const waiting = objects.filter((o) => !o.unreachable && !o.archived && o.parentRef && addressPointerOf(o.parentRef))
3166
+ if (waiting.length === 0) return
3167
+ const parents = [...new Set(waiting.map((o) => o.parentRef!))]
3168
+ const changes = await readArchiveChanges(parents, query)
3169
+ for (const object of waiting) {
3170
+ const archive = archiveOf(changes, object.parentRef!, ARCHIVE_RULE)
3171
+ if (archive) object.archived = { ...archive, with: object.parentRef! }
3172
+ }
3173
+ }
3174
+
3175
+ /**
3176
+ * Addresses per filter when reading archive changes. A filter's `limit` caps
3177
+ * every change naming its addresses — titles, statuses, moves — not only the
3178
+ * archives, and a relay answers newest first, so a small group keeps the
3179
+ * archive change inside the page.
3180
+ */
3181
+ const ARCHIVE_READ_GROUP = 25
3182
+
3183
+ /** The filters asking for every SPEC-shaped change naming these addresses. */
3184
+ function archiveFilters(addresses: readonly string[]): Record<string, unknown>[] {
3185
+ const filters: Record<string, unknown>[] = []
3186
+ for (let start = 0; start < addresses.length; start += ARCHIVE_READ_GROUP) {
3187
+ const group = addresses.slice(start, start + ARCHIVE_READ_GROUP)
3188
+ filters.push({ kinds: [ARCHIVE_RULE.changeKind], '#a': group, limit: RELAY_PAGE_CEILING })
3189
+ }
3190
+ return filters
3191
+ }
3192
+
3193
+ /** Every SPEC-shaped change naming these addresses, in as few requests as the relay allows. */
3194
+ async function readArchiveChanges(addresses: readonly string[], query: QueryFn): Promise<SignedEvent[]> {
3195
+ const filters = archiveFilters(addresses)
3196
+ const events: SignedEvent[] = []
3197
+ for (let start = 0; start < filters.length; start += MAX_FILTERS_PER_QUERY) {
3198
+ events.push(...(await query(filters.slice(start, start + MAX_FILTERS_PER_QUERY))))
3199
+ }
3200
+ return events
3201
+ }
3202
+
2978
3203
  /** An `naddr` or a `<kind>:<pubkey>:<d>`, or null for anything else. */
2979
3204
  function addressPointerOf(reference: string): AddressPointer | null {
2980
3205
  try {
@@ -3046,6 +3271,9 @@ function planObject(
3046
3271
  { kinds: [pointer.kind], authors: [pointer.pubkey], '#d': [pointer.identifier], limit: 1 },
3047
3272
  // Only when the app actually declares a change kind — see `foldRuleOf`.
3048
3273
  ...(manifest.records ? [{ kinds: [manifest.records.changeKind], '#a': [address], limit: 500 }] : []),
3274
+ // Every file may be archived, including one whose app folds nothing
3275
+ // (FOL-46). SPEC's change kind, when the app has not named its own.
3276
+ ...(manifest.records ? [] : [{ kinds: [ARCHIVE_RULE.changeKind], '#a': [address], limit: 500 }]),
3049
3277
  { kinds: commentKinds, '#a': [address], limit: CONVERSATION_LIMIT },
3050
3278
  ...(childFilter ? [childFilter.filter] : []),
3051
3279
  ]
@@ -3147,6 +3375,7 @@ function assembleObject(plan: ObjectPlan, answered: SignedEvent[]): AssembledObj
3147
3375
  viaRecommendation,
3148
3376
  webTemplate: resolved.webTemplate,
3149
3377
  comments,
3378
+ archived: archiveOf(events, address, archiveRuleOf(manifest)),
3150
3379
  })
3151
3380
  /*
3152
3381
  The `list` slot — PRO-7.
@@ -4294,6 +4523,12 @@ export interface ActionEventArgs {
4294
4523
  * marker text, which is always correct.
4295
4524
  */
4296
4525
  contentFormat?: string
4526
+ /**
4527
+ * What the person said about a change, carried as its `content` — the
4528
+ * resolution summary of an archive (FOL-46), or any change's note. A change
4529
+ * only: a comment's text is its `value`, and a creation has its own body.
4530
+ */
4531
+ note?: string
4297
4532
  pubkey: string
4298
4533
  createdAtMs: number
4299
4534
  }
@@ -4398,6 +4633,11 @@ function buildOneActionEvent(args: ActionEventArgs): UnsignedActionEvent | strin
4398
4633
  if (args.contentFormat !== undefined && !isCreation && (!declared.emits.field || declared.emits.kind === KIND_DELETION)) {
4399
4634
  return `"${declared.label}" takes no prose value, so it takes no content format.`
4400
4635
  }
4636
+ // A note is a change's `content`. Anywhere else it would be dropped, and the
4637
+ // resolution a person typed lost without a word.
4638
+ if (args.note !== undefined && (isCreation || !declared.emits.field || declared.emits.kind === KIND_DELETION)) {
4639
+ return `"${declared.label}" is not a change, so it takes no note.`
4640
+ }
4401
4641
 
4402
4642
  // An object-creating action is a different event entirely — a new object
4403
4643
  // rather than a change to one — so it branches before the scalar path.
@@ -4516,7 +4756,7 @@ function buildOneActionEvent(args: ActionEventArgs): UnsignedActionEvent | strin
4516
4756
  created_at: Math.floor(args.createdAtMs / 1000),
4517
4757
  kind: declared.emits.kind,
4518
4758
  tags,
4519
- content: declared.emits.field ? '' : value,
4759
+ content: declared.emits.field ? (args.note ?? '') : value,
4520
4760
  }
4521
4761
  }
4522
4762
 
@@ -4604,6 +4844,25 @@ export interface FolderSummary {
4604
4844
  * another app's files resolves them with {@link resolveFolderContents}.
4605
4845
  */
4606
4846
  addresses?: string[]
4847
+ /**
4848
+ * The Folder's own address as a file — its `kind:39000`, `39000:<relay>:<id>`.
4849
+ * What a state lists when it holds this Folder, and what an `archived`
4850
+ * change on the Folder names. Absent only for a state whose channel the
4851
+ * relay did not return.
4852
+ */
4853
+ channel?: string
4854
+ /**
4855
+ * Present when the Folder is archived (FOL-46) — or, for a record's channel,
4856
+ * when the record it belongs to is (`with` names the record). See
4857
+ * {@link Archive}.
4858
+ *
4859
+ * {@link topLevelFolders} leaves an archived Folder out, and
4860
+ * {@link resolveFolderContents} leaves one out of the Folder that lists it,
4861
+ * so its subtree goes with it. What it holds stays readable: a link still
4862
+ * opens it, and a file it lists that another Folder also lists stays visible
4863
+ * there.
4864
+ */
4865
+ archived?: Archive
4607
4866
  }
4608
4867
 
4609
4868
  /**
@@ -4620,9 +4879,14 @@ export interface FolderSummary {
4620
4879
  *
4621
4880
  * Not a list of ids: a new team is a folder somebody creates, not a code
4622
4881
  * change. Moved here from Peek and Ship, which each held the same line.
4882
+ *
4883
+ * An archived Folder is not navigated by (FOL-46), and a listing that has not
4884
+ * read archives — a summary with no `archived` field — keeps every Folder.
4623
4885
  */
4624
- export function topLevelFolders<T extends Pick<FolderSummary, 'hasState' | 'listedIn'>>(folders: T[]): T[] {
4625
- return folders.filter((folder) => folder.hasState && !folder.listedIn?.length)
4886
+ export function topLevelFolders<T extends Pick<FolderSummary, 'hasState' | 'listedIn' | 'archived'>>(
4887
+ folders: T[],
4888
+ ): T[] {
4889
+ return folders.filter((folder) => folder.hasState && !folder.listedIn?.length && !folder.archived)
4626
4890
  }
4627
4891
 
4628
4892
  /** A folder and everything in it, each file drawn through its owner's manifest. */
@@ -4687,6 +4951,11 @@ export async function listFolders(query: QueryFn): Promise<FolderSummary[]> {
4687
4951
  ...(addresses.length ? { addresses } : {}),
4688
4952
  })
4689
4953
  }
4954
+ for (const event of events) {
4955
+ const id = tagValue(event, 'd')
4956
+ const folder = id && event.kind === KIND_CHANNEL ? byId.get(id) : undefined
4957
+ if (folder) folder.channel = pointerToAddress({ kind: KIND_CHANNEL, pubkey: event.pubkey, identifier: id!, relays: [] })
4958
+ }
4690
4959
  /*
4691
4960
  A folder listed in another folder's state is a file there. Read off the
4692
4961
  states already in hand: an `a` naming a `kind:39000` is a channel, and its
@@ -4707,14 +4976,199 @@ export async function listFolders(query: QueryFn): Promise<FolderSummary[]> {
4707
4976
  listedIn.set(identifier, containers)
4708
4977
  }
4709
4978
  }
4710
- await placeRecordChannels(events, byId, listedIn, query)
4979
+ const { recordsOf, archives } = await placeRecordChannels(events, byId, listedIn, query)
4711
4980
  for (const [id, containers] of listedIn) {
4712
4981
  const folder = byId.get(id)
4713
4982
  if (folder) folder.listedIn = containers
4714
4983
  }
4984
+ markArchivedFolders(byId, recordsOf, archives)
4715
4985
  return [...byId.values()].sort((a, b) => (a.name ?? a.id).localeCompare(b.name ?? b.id))
4716
4986
  }
4717
4987
 
4988
+ /**
4989
+ * Which Folders are archived — FOL-46, from the changes {@link placeRecordChannels}
4990
+ * read with the record roots.
4991
+ *
4992
+ * A Folder is archived by a change naming its channel's address, the way any
4993
+ * file is. A record's channel — a Ship project's conversation — is archived
4994
+ * with its record, so an archived project's channel stops lighting its team's
4995
+ * dot the way the project stopped being listed — only when every record naming
4996
+ * the channel is archived, since two projects may share one. Its own archive
4997
+ * wins when it has one.
4998
+ *
4999
+ * A refused read throws before this, like the reads beside it: a listing that
5000
+ * silently reported every Folder live would put archived teams back in
5001
+ * everyone's sidebar.
5002
+ */
5003
+ function markArchivedFolders(
5004
+ byId: Map<string, FolderSummary>,
5005
+ recordsOf: Map<string, string[]>,
5006
+ changes: SignedEvent[],
5007
+ ): void {
5008
+ for (const folder of byId.values()) {
5009
+ const own = folder.channel ? archiveOf(changes, folder.channel, ARCHIVE_RULE) : undefined
5010
+ if (own) {
5011
+ folder.archived = own
5012
+ continue
5013
+ }
5014
+ const records = recordsOf.get(folder.id) ?? []
5015
+ const archives = records.map((record) => archiveOf(changes, record, ARCHIVE_RULE))
5016
+ if (records.length && archives.every(Boolean)) folder.archived = { ...archives[0]!, with: records[0] }
5017
+ }
5018
+ }
5019
+
5020
+ /** How many Folders deep {@link archiveImpact} follows nested Folders. A request per Folder. */
5021
+ const MAX_ARCHIVE_DEPTH = 3
5022
+
5023
+ /** What archiving one file would hide, for the warning a person reads first — FOL-46. */
5024
+ export interface ArchiveImpact {
5025
+ /**
5026
+ * The files that would go out of every list with it, counted by kind: its
5027
+ * children, and — for a Folder — every file only that Folder lists, with
5028
+ * their children. Files already archived are not counted; they are hidden
5029
+ * already. Kinds with no files are absent.
5030
+ */
5031
+ hides: { kind: number; count: number }[]
5032
+ /**
5033
+ * Files a Folder lists that another Folder, not archived, lists too. They
5034
+ * stay visible there, and a warning that said they would be hidden would
5035
+ * make Archive look more destructive than it is. Empty for a file that is
5036
+ * not a Folder.
5037
+ */
5038
+ staysVisible: { address: string; kind: number; in: { id: string; name?: string }[] }[]
5039
+ }
5040
+
5041
+ /**
5042
+ * Count what archiving `address` would hide — the read behind the warning.
5043
+ *
5044
+ * "Hides 14 issues and 6 topics that are only here; 2 topics also in Estiva HQ
5045
+ * stay visible." The words are the app's; the counts are the same in every
5046
+ * app, which is why they are read here.
5047
+ *
5048
+ * - **A Folder** (a `kind:39000` address, `FolderSummary.channel`): what it
5049
+ * lists, split by whether another Folder lists it too, the children of what
5050
+ * would be hidden, and — three Folders deep — what a nested Folder only it
5051
+ * lists holds. Pass `folders` from the app's own `listFolders` to save that
5052
+ * read.
5053
+ * - **Any other file**: the children its kind declares (a project's issues), and
5054
+ * bare files placed under it (sub-topics), by their root's `a` tag.
5055
+ *
5056
+ * One level of children, as a listing draws them. A few requests, whatever the
5057
+ * size: the Folder, one per app's manifest (memoised by `cache`), the children,
5058
+ * and their archives.
5059
+ */
5060
+ export async function archiveImpact(
5061
+ address: string,
5062
+ query: QueryFn,
5063
+ options: { folders?: FolderSummary[]; cache?: ProjectionCache } = {},
5064
+ ): Promise<ArchiveImpact> {
5065
+ const pointer = addressPointerOf(address)
5066
+ if (!pointer) return { hides: [], staysVisible: [] }
5067
+ const counts = new Map<number, number>()
5068
+ const count = (kind: number, n = 1) => counts.set(kind, (counts.get(kind) ?? 0) + n)
5069
+ const staysVisible: ArchiveImpact['staysVisible'] = []
5070
+ let parents: { address: string; pointer: AddressPointer }[] = [{ address, pointer }]
5071
+
5072
+ if (pointer.kind === KIND_CHANNEL) {
5073
+ const folders = options.folders ?? (await listFolders(query))
5074
+ parents = []
5075
+ /*
5076
+ A nested Folder only this one lists goes out of view with it, and so does
5077
+ everything only *that* one lists — walked the same way, a Folder at a
5078
+ time, to a small depth. "Only" is judged against the live Folders outside
5079
+ the tree being archived.
5080
+ */
5081
+ const inTree = new Set([pointer.identifier])
5082
+ const walk = async (folder: string, depth: number) => {
5083
+ const contents = await resolveFolderContents(folder, query, async () => ({}), options.cache)
5084
+ for (const file of contents.files) {
5085
+ if (!file.address) continue
5086
+ const others = folders.filter(
5087
+ (other) => !inTree.has(other.id) && !other.archived && other.addresses?.includes(file.address!),
5088
+ )
5089
+ if (others.length) {
5090
+ staysVisible.push({ address: file.address, kind: file.kind, in: others.map(({ id, name }) => ({ id, name })) })
5091
+ continue
5092
+ }
5093
+ count(file.kind)
5094
+ const filePointer = addressPointerOf(file.address)
5095
+ if (!filePointer) continue
5096
+ if (filePointer.kind === KIND_CHANNEL) {
5097
+ if (depth < MAX_ARCHIVE_DEPTH && !inTree.has(filePointer.identifier)) {
5098
+ inTree.add(filePointer.identifier)
5099
+ await walk(filePointer.identifier, depth + 1)
5100
+ }
5101
+ } else {
5102
+ parents.push({ address: file.address, pointer: filePointer })
5103
+ }
5104
+ }
5105
+ }
5106
+ await walk(pointer.identifier, 0)
5107
+ }
5108
+
5109
+ // A record channel lists a project *and* its issues; each is counted once.
5110
+ const counted = new Set(parents.map((p) => p.address))
5111
+ for (const [kind, n] of await countLiveChildren(parents, counted, query, options.cache)) count(kind, n)
5112
+ return {
5113
+ hides: [...counts].map(([kind, n]) => ({ kind, count: n })),
5114
+ staysVisible,
5115
+ }
5116
+ }
5117
+
5118
+ /** The children of each parent that are not archived already, by kind. */
5119
+ async function countLiveChildren(
5120
+ parents: { address: string; pointer: AddressPointer }[],
5121
+ counted: ReadonlySet<string>,
5122
+ query: QueryFn,
5123
+ cache?: ProjectionCache,
5124
+ ): Promise<Map<number, number>> {
5125
+ const byKind = new Map<number, number>()
5126
+ if (parents.length === 0) return byKind
5127
+ const byApp = new Map<string, AddressPointer>()
5128
+ for (const { pointer } of parents) byApp.set(manifestKeyOf(pointer), pointer)
5129
+ const manifests = new Map<string, ResolvedManifest>()
5130
+ await Promise.all(
5131
+ [...byApp].map(async ([key, pointer]) => {
5132
+ const resolved = await resolveManifest(pointer, query, cache)
5133
+ if (resolved) manifests.set(key, resolved)
5134
+ }),
5135
+ )
5136
+ const filters: Record<string, unknown>[] = []
5137
+ const wanted: { kind: number; via: string; parent: string }[] = []
5138
+ for (const { address, pointer } of parents) {
5139
+ const projection = manifests.get(manifestKeyOf(pointer))?.manifest.projections?.[String(pointer.kind)]
5140
+ const declared = projection && declaredChildSpec(projection)
5141
+ const specs = [
5142
+ ...(declared ? [{ kind: declared.kind, via: declared.via }] : []),
5143
+ // A sub-topic may sit under a file of any kind (SPEC §6.7).
5144
+ ...(declared?.kind === KIND_BARE_FILE && declared.via === 'a' ? [] : [{ kind: KIND_BARE_FILE, via: 'a' }]),
5145
+ ]
5146
+ for (const spec of specs) {
5147
+ wanted.push({ ...spec, parent: address })
5148
+ filters.push({ kinds: [spec.kind], [`#${spec.via}`]: [address], limit: RELAY_PAGE_CEILING })
5149
+ }
5150
+ }
5151
+ const events: SignedEvent[] = []
5152
+ for (let start = 0; start < filters.length; start += MAX_FILTERS_PER_QUERY) {
5153
+ events.push(...(await query(filters.slice(start, start + MAX_FILTERS_PER_QUERY))))
5154
+ }
5155
+ const children = new Map<string, number>()
5156
+ for (const event of events) {
5157
+ const identifier = tagValue(event, 'd')
5158
+ if (identifier === undefined) continue
5159
+ if (!wanted.some((w) => w.kind === event.kind && hasTagValue(event, w.via, w.parent))) continue
5160
+ const child = pointerToAddress({ kind: event.kind, pubkey: event.pubkey, identifier, relays: [] })
5161
+ if (!counted.has(child)) children.set(child, event.kind)
5162
+ }
5163
+ if (children.size === 0) return byKind
5164
+ const changes = await readArchiveChanges([...children.keys()], query)
5165
+ for (const [child, kind] of children) {
5166
+ if (archiveOf(changes, child, ARCHIVE_RULE)) continue
5167
+ byKind.set(kind, (byKind.get(kind) ?? 0) + 1)
5168
+ }
5169
+ return byKind
5170
+ }
5171
+
4718
5172
  /**
4719
5173
  * A record's own channel is listed wherever the record is (FOL-42).
4720
5174
  *
@@ -4763,7 +5217,7 @@ async function placeRecordChannels(
4763
5217
  byId: Map<string, FolderSummary>,
4764
5218
  listedIn: Map<string, string[]>,
4765
5219
  query: QueryFn,
4766
- ): Promise<void> {
5220
+ ): Promise<{ recordsOf: Map<string, string[]>; archives: SignedEvent[] }> {
4767
5221
  const containersOf = new Map<string, { pointer: AddressPointer; containers: string[] }>()
4768
5222
  for (const event of events) {
4769
5223
  if (event.kind !== KIND_FOLDER_STATE) continue
@@ -4784,7 +5238,18 @@ async function placeRecordChannels(
4784
5238
  containersOf.set(key, entry)
4785
5239
  }
4786
5240
  }
4787
- if (containersOf.size === 0) return
5241
+ // Every Folder's archive, and every listed record's, ride with the roots
5242
+ // (FOL-46): the channel addresses are in hand from the listing and the
5243
+ // record addresses are the keys above, so neither needs the roots first.
5244
+ const channels = [...byId.values()].flatMap((folder) => (folder.channel ? [folder.channel] : []))
5245
+ const archiveAsk = archiveFilters([...new Set([...channels, ...containersOf.keys()])])
5246
+ if (containersOf.size === 0) {
5247
+ const archives: SignedEvent[] = []
5248
+ for (let start = 0; start < archiveAsk.length; start += MAX_FILTERS_PER_QUERY) {
5249
+ archives.push(...(await query(archiveAsk.slice(start, start + MAX_FILTERS_PER_QUERY))))
5250
+ }
5251
+ return { recordsOf: new Map(), archives }
5252
+ }
4788
5253
 
4789
5254
  const groups = new Map<string, { kind: number; pubkey: string; identifiers: string[] }>()
4790
5255
  for (const { pointer } of containersOf.values()) {
@@ -4800,10 +5265,14 @@ async function placeRecordChannels(
4800
5265
  filters.push({ kinds: [kind], authors: [pubkey], '#d': chunk, limit: chunk.length })
4801
5266
  }
4802
5267
  }
4803
- const roots: SignedEvent[] = []
5268
+ filters.push(...archiveAsk)
5269
+ const answered: SignedEvent[] = []
4804
5270
  for (let start = 0; start < filters.length; start += MAX_FILTERS_PER_QUERY) {
4805
- roots.push(...(await query(filters.slice(start, start + MAX_FILTERS_PER_QUERY))))
5271
+ answered.push(...(await query(filters.slice(start, start + MAX_FILTERS_PER_QUERY))))
4806
5272
  }
5273
+ // A state lists files, never change events, so the kind tells them apart.
5274
+ const archives = answered.filter((e) => e.kind === ARCHIVE_RULE.changeKind)
5275
+ const roots = answered.filter((e) => e.kind !== ARCHIVE_RULE.changeKind)
4807
5276
 
4808
5277
  // Newest wins, as it does for any addressable event a relay has not yet replaced.
4809
5278
  const newest = new Map<string, SignedEvent>()
@@ -4812,10 +5281,14 @@ async function placeRecordChannels(
4812
5281
  const held = newest.get(key)
4813
5282
  if (!held || root.created_at > held.created_at) newest.set(key, root)
4814
5283
  }
5284
+ const recordsOf = new Map<string, string[]>()
4815
5285
  for (const [key, { containers }] of containersOf) {
4816
5286
  const root = newest.get(key)
4817
5287
  const channel = root && folderOf(root)
4818
5288
  if (!channel || byId.get(channel)?.hasState) continue
5289
+ // A file published into the Folder that lists it names that Folder, and
5290
+ // does not own it: a topic's `h` is its team's.
5291
+ if (!containers.includes(channel)) recordsOf.set(channel, [...(recordsOf.get(channel) ?? []), key])
4819
5292
  for (const container of containers) {
4820
5293
  if (container === channel) continue
4821
5294
  const placed = listedIn.get(channel) ?? []
@@ -4823,6 +5296,7 @@ async function placeRecordChannels(
4823
5296
  listedIn.set(channel, placed)
4824
5297
  }
4825
5298
  }
5299
+ return { recordsOf, archives }
4826
5300
  }
4827
5301
 
4828
5302
  /**
@@ -4875,6 +5349,14 @@ export async function resolveFolderContents(
4875
5349
  lookupPeople?: PeopleFn,
4876
5350
  /** See {@link ProjectionCache}. Omitting it is exactly the old behaviour. */
4877
5351
  cache?: ProjectionCache,
5352
+ options: {
5353
+ /**
5354
+ * Return archived files — and files hidden with an archived parent — each
5355
+ * carrying its {@link Archive}, instead of leaving them out. For a view
5356
+ * that lists what was archived; every other list wants the default.
5357
+ */
5358
+ includeArchived?: boolean
5359
+ } = {},
4878
5360
  ): Promise<FolderContents> {
4879
5361
  // 1. The folder itself. Both kinds in one trip: the state is the model and
4880
5362
  // the channel is what names a folder that has none yet.
@@ -4884,11 +5366,15 @@ export async function resolveFolderContents(
4884
5366
  ])
4885
5367
  const state = identity.find((e) => e.kind === KIND_FOLDER_STATE && tagValue(e, 'd') === folder)
4886
5368
  const channel = identity.find((e) => e.kind === KIND_CHANNEL && tagValue(e, 'd') === folder)
5369
+ const channelAddress = channel
5370
+ ? pointerToAddress({ kind: KIND_CHANNEL, pubkey: channel.pubkey, identifier: folder, relays: [] })
5371
+ : undefined
4887
5372
 
4888
5373
  const summary: FolderSummary & { address?: string } = {
4889
5374
  id: folder,
4890
5375
  name: nameOf(state) ?? nameOf(channel),
4891
5376
  hasState: !!state,
5377
+ ...(channelAddress ? { channel: channelAddress } : {}),
4892
5378
  ...(state
4893
5379
  ? { address: pointerToAddress({ kind: state.kind, pubkey: state.pubkey, identifier: folder, relays: [] }) }
4894
5380
  : {}),
@@ -4904,7 +5390,12 @@ export async function resolveFolderContents(
4904
5390
  : await addressesByContainment(folder, query)
4905
5391
 
4906
5392
  if (addresses.length === 0) {
4907
- return { ...summary, files: [], source: state ? 'state' : 'channel' }
5393
+ // Nothing listed, so no change query to ride on: the Folder's own archive
5394
+ // is one small read of its own.
5395
+ const archived = channelAddress
5396
+ ? archiveOf(await readArchiveChanges([channelAddress], query), channelAddress, ARCHIVE_RULE)
5397
+ : undefined
5398
+ return { ...summary, ...(archived ? { archived } : {}), files: [], source: state ? 'state' : 'channel' }
4908
5399
  }
4909
5400
 
4910
5401
  // 2. Group by (kind, author): one manifest answers for every file an app owns
@@ -4943,10 +5434,15 @@ export async function resolveFolderContents(
4943
5434
  // Change kinds are a set because two apps may fold differently, and a kind
4944
5435
  // is a u16 — the relay refuses an out-of-range one outright, so an app
4945
5436
  // declaring no `records` contributes no filter rather than an empty one.
5437
+ //
5438
+ // SPEC's change kind is always asked for, whatever the apps declare: any
5439
+ // file may be archived (FOL-46), a nested Folder included, and so may this
5440
+ // Folder, whose own address rides in the same filter.
4946
5441
  const changeKinds = [
4947
- ...new Set(
4948
- [...manifests.values()].flatMap((r) => (r.manifest.records ? [r.manifest.records.changeKind] : [])),
4949
- ),
5442
+ ...new Set([
5443
+ ARCHIVE_RULE.changeKind,
5444
+ ...[...manifests.values()].flatMap((r) => (r.manifest.records ? [r.manifest.records.changeKind] : [])),
5445
+ ]),
4950
5446
  ]
4951
5447
  const events = await query([
4952
5448
  ...[...groups.values()].map(({ pointer, addresses: group }) => ({
@@ -4955,13 +5451,21 @@ export async function resolveFolderContents(
4955
5451
  '#d': group.map((a) => referenceToPointer(a).identifier),
4956
5452
  limit: group.length,
4957
5453
  })),
4958
- ...(changeKinds.length
4959
- ? [{ kinds: changeKinds, '#a': addresses, limit: 500 }]
4960
- : []),
5454
+ { kinds: changeKinds, '#a': addresses, limit: 500 },
5455
+ // The archives again, in groups small enough that a busy Folder's other
5456
+ // changes cannot push them off the page — the filter above holds 500
5457
+ // changes for every file together, and one Folder has already had 688.
5458
+ // Same request.
5459
+ ...archiveFilters(channelAddress ? [...addresses, channelAddress] : addresses),
4961
5460
  ])
4962
-
4963
- // 4. Build each file, in the order the folder listed them.
4964
- const files: ForeignObject[] = []
5461
+ const ownArchive = channelAddress ? archiveOf(events, channelAddress, ARCHIVE_RULE) : undefined
5462
+ if (ownArchive) summary.archived = ownArchive
5463
+
5464
+ // 4. Build each file, in the order the folder listed them. Archived files are
5465
+ // held back until the cascade below has read their parents.
5466
+ const listed: { file: ForeignObject; archive?: Archive }[] = []
5467
+ const archiveByAddress = new Map<string, Archive | undefined>()
5468
+ const parentByAddress = new Map<string, string | undefined>()
4965
5469
  for (const { address, pointer } of pointers) {
4966
5470
  const resolved = manifests.get(manifestKeyOf(pointer))
4967
5471
  // No app claims this kind, so there is no projection to draw it with.
@@ -4979,11 +5483,16 @@ export async function resolveFolderContents(
4979
5483
  events.filter((e) => e.kind === records.changeKind && hasTagValue(e, records.targetTag, address)),
4980
5484
  records,
4981
5485
  )
5486
+ const archive = archiveOf(events, address, archiveRuleOf(resolved.manifest))
5487
+ archiveByAddress.set(address, archive)
5488
+ parentByAddress.set(address, parentRefOf(resolved.manifest, pointer.kind, root, folded))
4982
5489
  // An app hiding a record from its own lists is saying it is not part of the
4983
- // folder any more. `hiddenWhen` is the app's own declaration of that.
4984
- if (records.hiddenWhen && folded[records.hiddenWhen.field]?.value === records.hiddenWhen.equals) {
4985
- continue
4986
- }
5490
+ // folder any more. `hiddenWhen` is the app's own declaration of that — the
5491
+ // archive above is the same statement for a kind whose app declared none.
5492
+ // Not reported as an archive: the app said "hidden", which may mean more.
5493
+ const hidden =
5494
+ !!records.hiddenWhen && folded[records.hiddenWhen.field]?.value === records.hiddenWhen.equals
5495
+ if (hidden && !archive) continue
4987
5496
  /*
4988
5497
  A placed file stays listed only while the placement is current.
4989
5498
 
@@ -5008,8 +5517,9 @@ export async function resolveFolderContents(
5008
5517
  })
5009
5518
  if (!current) continue
5010
5519
  }
5011
- files.push(
5012
- buildObject({
5520
+ listed.push({
5521
+ archive,
5522
+ file: buildObject({
5013
5523
  root,
5014
5524
  pointer,
5015
5525
  manifest: resolved.manifest,
@@ -5018,7 +5528,45 @@ export async function resolveFolderContents(
5018
5528
  viaRecommendation: resolved.viaRecommendation,
5019
5529
  webTemplate: resolved.webTemplate,
5020
5530
  }),
5021
- )
5531
+ })
5532
+ }
5533
+
5534
+ /*
5535
+ 5. The cascade (FOL-46): a file under an archived file is hidden with it —
5536
+ an issue with its project, a sub-topic with its topic. Computed here and
5537
+ never written to the children, so unarchiving the parent restores
5538
+ exactly what was there.
5539
+
5540
+ The chain is walked through everything this Folder lists. A parent that
5541
+ lives in another Folder is read once for all such parents, one level: a
5542
+ project whose record channel lists its issues is the case that matters,
5543
+ and there the project is listed too.
5544
+
5545
+ Only by parent. A file this Folder lists is never hidden because some
5546
+ *other* Folder that lists it is archived — that is what lets a file
5547
+ placed in two Folders stay visible in the one that is not archived.
5548
+ */
5549
+ const outside = [
5550
+ ...new Set(
5551
+ listed.flatMap(({ file }) => {
5552
+ const parent = file.address && parentByAddress.get(file.address)
5553
+ return parent && !archiveByAddress.has(parent) && addressPointerOf(parent) ? [parent] : []
5554
+ }),
5555
+ ),
5556
+ ]
5557
+ if (outside.length) {
5558
+ const changes = await readArchiveChanges(outside, query)
5559
+ for (const parent of outside) archiveByAddress.set(parent, archiveOf(changes, parent, ARCHIVE_RULE))
5560
+ }
5561
+ const files: ForeignObject[] = []
5562
+ for (const { file, archive } of listed) {
5563
+ const effective =
5564
+ archive ??
5565
+ (file.address
5566
+ ? archivedAncestorOf(file.address, (a) => parentByAddress.get(a), (a) => archiveByAddress.get(a))
5567
+ : undefined)
5568
+ if (!effective) files.push(file)
5569
+ else if (options.includeArchived) files.push({ ...file, archived: effective })
5022
5570
  }
5023
5571
 
5024
5572
  const people = await (lookupPeople ?? peopleViaRelay(query))([