@semiont/core 0.5.28 → 0.5.29

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -848,275 +848,6 @@ interface paths {
848
848
  patch?: never;
849
849
  trace?: never;
850
850
  };
851
- "/api/admin/exchange/backup": {
852
- parameters: {
853
- query?: never;
854
- header?: never;
855
- path?: never;
856
- cookie?: never;
857
- };
858
- get?: never;
859
- put?: never;
860
- /**
861
- * Backup Knowledge Base
862
- * @description Create a lossless backup of the knowledge base as a streaming tar.gz archive
863
- */
864
- post: {
865
- parameters: {
866
- query?: never;
867
- header?: never;
868
- path?: never;
869
- cookie?: never;
870
- };
871
- requestBody?: never;
872
- responses: {
873
- /** @description Streaming backup archive */
874
- 200: {
875
- headers: {
876
- [name: string]: unknown;
877
- };
878
- content: {
879
- "application/gzip": string;
880
- };
881
- };
882
- /** @description Unauthorized */
883
- 401: {
884
- headers: {
885
- [name: string]: unknown;
886
- };
887
- content: {
888
- "application/json": components["schemas"]["ErrorResponse"];
889
- };
890
- };
891
- /** @description Forbidden - Admin access required */
892
- 403: {
893
- headers: {
894
- [name: string]: unknown;
895
- };
896
- content: {
897
- "application/json": components["schemas"]["ErrorResponse"];
898
- };
899
- };
900
- };
901
- };
902
- delete?: never;
903
- options?: never;
904
- head?: never;
905
- patch?: never;
906
- trace?: never;
907
- };
908
- "/api/admin/exchange/restore": {
909
- parameters: {
910
- query?: never;
911
- header?: never;
912
- path?: never;
913
- cookie?: never;
914
- };
915
- get?: never;
916
- put?: never;
917
- /**
918
- * Restore Knowledge Base
919
- * @description Restore knowledge base from a backup archive. Returns SSE progress events.
920
- */
921
- post: {
922
- parameters: {
923
- query?: never;
924
- header?: never;
925
- path?: never;
926
- cookie?: never;
927
- };
928
- requestBody: {
929
- content: {
930
- "multipart/form-data": {
931
- /**
932
- * Format: binary
933
- * @description Backup archive (.tar.gz)
934
- */
935
- file: string;
936
- };
937
- };
938
- };
939
- responses: {
940
- /** @description SSE stream of restore progress events */
941
- 200: {
942
- headers: {
943
- [name: string]: unknown;
944
- };
945
- content: {
946
- "text/event-stream": string;
947
- };
948
- };
949
- /** @description Invalid file format */
950
- 400: {
951
- headers: {
952
- [name: string]: unknown;
953
- };
954
- content: {
955
- "application/json": components["schemas"]["ErrorResponse"];
956
- };
957
- };
958
- /** @description Unauthorized */
959
- 401: {
960
- headers: {
961
- [name: string]: unknown;
962
- };
963
- content: {
964
- "application/json": components["schemas"]["ErrorResponse"];
965
- };
966
- };
967
- /** @description Forbidden - Admin access required */
968
- 403: {
969
- headers: {
970
- [name: string]: unknown;
971
- };
972
- content: {
973
- "application/json": components["schemas"]["ErrorResponse"];
974
- };
975
- };
976
- };
977
- };
978
- delete?: never;
979
- options?: never;
980
- head?: never;
981
- patch?: never;
982
- trace?: never;
983
- };
984
- "/api/moderate/exchange/export": {
985
- parameters: {
986
- query?: never;
987
- header?: never;
988
- path?: never;
989
- cookie?: never;
990
- };
991
- get?: never;
992
- put?: never;
993
- /**
994
- * Export Knowledge Base as JSON-LD
995
- * @description Export the knowledge base as a JSON-LD Linked Data tar.gz archive
996
- */
997
- post: {
998
- parameters: {
999
- query?: {
1000
- /** @description Include archived resources in export */
1001
- includeArchived?: boolean;
1002
- };
1003
- header?: never;
1004
- path?: never;
1005
- cookie?: never;
1006
- };
1007
- requestBody?: never;
1008
- responses: {
1009
- /** @description Streaming JSON-LD archive */
1010
- 200: {
1011
- headers: {
1012
- [name: string]: unknown;
1013
- };
1014
- content: {
1015
- "application/gzip": string;
1016
- };
1017
- };
1018
- /** @description Unauthorized */
1019
- 401: {
1020
- headers: {
1021
- [name: string]: unknown;
1022
- };
1023
- content: {
1024
- "application/json": components["schemas"]["ErrorResponse"];
1025
- };
1026
- };
1027
- /** @description Forbidden - moderator or admin role required */
1028
- 403: {
1029
- headers: {
1030
- [name: string]: unknown;
1031
- };
1032
- content: {
1033
- "application/json": components["schemas"]["ErrorResponse"];
1034
- };
1035
- };
1036
- };
1037
- };
1038
- delete?: never;
1039
- options?: never;
1040
- head?: never;
1041
- patch?: never;
1042
- trace?: never;
1043
- };
1044
- "/api/moderate/exchange/import": {
1045
- parameters: {
1046
- query?: never;
1047
- header?: never;
1048
- path?: never;
1049
- cookie?: never;
1050
- };
1051
- get?: never;
1052
- put?: never;
1053
- /**
1054
- * Import Knowledge Base from JSON-LD
1055
- * @description Import resources from a JSON-LD Linked Data archive. Returns SSE progress events.
1056
- */
1057
- post: {
1058
- parameters: {
1059
- query?: never;
1060
- header?: never;
1061
- path?: never;
1062
- cookie?: never;
1063
- };
1064
- requestBody: {
1065
- content: {
1066
- "multipart/form-data": {
1067
- /**
1068
- * Format: binary
1069
- * @description JSON-LD archive (.tar.gz)
1070
- */
1071
- file: string;
1072
- };
1073
- };
1074
- };
1075
- responses: {
1076
- /** @description SSE stream of import progress events */
1077
- 200: {
1078
- headers: {
1079
- [name: string]: unknown;
1080
- };
1081
- content: {
1082
- "text/event-stream": string;
1083
- };
1084
- };
1085
- /** @description Invalid file format */
1086
- 400: {
1087
- headers: {
1088
- [name: string]: unknown;
1089
- };
1090
- content: {
1091
- "application/json": components["schemas"]["ErrorResponse"];
1092
- };
1093
- };
1094
- /** @description Unauthorized */
1095
- 401: {
1096
- headers: {
1097
- [name: string]: unknown;
1098
- };
1099
- content: {
1100
- "application/json": components["schemas"]["ErrorResponse"];
1101
- };
1102
- };
1103
- /** @description Forbidden - moderator or admin role required */
1104
- 403: {
1105
- headers: {
1106
- [name: string]: unknown;
1107
- };
1108
- content: {
1109
- "application/json": components["schemas"]["ErrorResponse"];
1110
- };
1111
- };
1112
- };
1113
- };
1114
- delete?: never;
1115
- options?: never;
1116
- head?: never;
1117
- patch?: never;
1118
- trace?: never;
1119
- };
1120
851
  "/api/cookies/consent": {
1121
852
  parameters: {
1122
853
  query?: never;
@@ -1399,7 +1130,7 @@ interface paths {
1399
1130
  put?: never;
1400
1131
  /**
1401
1132
  * Create a resource
1402
- * @description Upload binary content + metadata as multipart/form-data. The backend writes content to disk, then emits yield:create on the bus; Stower persists it and returns a 202 with the new resourceId. Full reconciliation happens via SSE domain events (yield:created).
1133
+ * @description Upload binary content + metadata as multipart/form-data. The gateway writes content to disk, then emits yield:create on the bus; Stower persists it and returns a 202 with the new resourceId. Full reconciliation happens via SSE domain events (yield:created).
1403
1134
  *
1404
1135
  * Generation workers and the /know/compose page both hit this route — bytes always travel on the HTTP wire, never on the bus.
1405
1136
  */
@@ -1422,233 +1153,46 @@ interface paths {
1422
1153
  file: string;
1423
1154
  /** @description Media type of the content (e.g. text/plain, text/markdown, image/png) */
1424
1155
  format: string;
1425
- /** @description Where the content lives (file://... for local). Required — the client names the location; the server does not derive one. */
1426
- storageUri: string;
1427
- /** @description ISO 639-1 language code */
1428
- language?: string;
1429
- /** @description JSON-stringified array of entity type names */
1430
- entityTypes?: string;
1431
- /** @description For AI-generated resources: the annotation that triggered generation. Nested into generatedFrom.annotationId on the persisted event. */
1432
- sourceAnnotationId?: string;
1433
- /** @description For AI-generated resources: the source resource the generating annotation lives on. Nested into generatedFrom.resourceId on the persisted event. */
1434
- sourceResourceId?: string;
1435
- /** @description For AI-generated resources: the prompt that drove generation */
1436
- generationPrompt?: string;
1437
- /** @description For AI-generated resources: JSON-stringified Agent (single object or array), capturing which model/worker produced the content */
1438
- generator?: string;
1439
- /** @description 'true' or 'false' — whether the resource is a draft */
1440
- isDraft?: string;
1441
- };
1442
- };
1443
- };
1444
- responses: {
1445
- /** @description Resource accepted for creation */
1446
- 202: {
1447
- headers: {
1448
- [name: string]: unknown;
1449
- };
1450
- content: {
1451
- "application/json": components["schemas"]["CreateResourceResponse"];
1452
- };
1453
- };
1454
- /** @description Missing required fields (name, file, format, or storageUri), or the format's base MIME type is not a SupportedMediaType. The error message names the offending type. */
1455
- 400: {
1456
- headers: {
1457
- [name: string]: unknown;
1458
- };
1459
- content: {
1460
- "application/json": components["schemas"]["ErrorResponse"];
1461
- };
1462
- };
1463
- /** @description Authentication required */
1464
- 401: {
1465
- headers: {
1466
- [name: string]: unknown;
1467
- };
1468
- content: {
1469
- "application/json": components["schemas"]["ErrorResponse"];
1470
- };
1471
- };
1472
- };
1473
- };
1474
- delete?: never;
1475
- options?: never;
1476
- head?: never;
1477
- patch?: never;
1478
- trace?: never;
1479
- };
1480
- "/resources/{id}": {
1481
- parameters: {
1482
- query?: never;
1483
- header?: never;
1484
- path?: never;
1485
- cookie?: never;
1486
- };
1487
- /**
1488
- * Get a resource's stored representation (the pipe)
1489
- * @description Returns the stored representation's bytes, verbatim, with the stored media type in Content-Type (`application/octet-stream` when the stored metadata carries none). The Accept header is never read: there is no content negotiation and no transcoding, so the served bytes always hash to the representation's registered checksum.
1490
- *
1491
- * The resource's JSON-LD description (descriptor + annotations + inbound entity references) lives at GET /resources/{id}/jsonld; every content response advertises it via a `Link: rel="describedby"` header.
1492
- *
1493
- * Content is immutable (checksum-addressed), and this route is bearer-authenticated, so responses carry `Cache-Control: private, max-age=31536000, immutable`.
1494
- */
1495
- get: {
1496
- parameters: {
1497
- query?: never;
1498
- header?: never;
1499
- path: {
1500
- id: string;
1501
- };
1502
- cookie?: never;
1503
- };
1504
- requestBody?: never;
1505
- responses: {
1506
- /** @description The stored representation's bytes, verbatim */
1507
- 200: {
1508
- headers: {
1509
- /** @description `</resources/{id}/jsonld>; rel="describedby"; type="application/ld+json"` — where to dereference the resource's JSON-LD description */
1510
- Link?: string;
1511
- [name: string]: unknown;
1512
- };
1513
- content: {
1514
- "*/*": string;
1515
- };
1516
- };
1517
- /** @description Resource or representation not found */
1518
- 404: {
1519
- headers: {
1520
- [name: string]: unknown;
1521
- };
1522
- content: {
1523
- "application/json": components["schemas"]["ErrorResponse"];
1524
- };
1525
- };
1526
- /** @description Failed to retrieve resource */
1527
- 500: {
1528
- headers: {
1529
- [name: string]: unknown;
1530
- };
1531
- content: {
1532
- "application/json": components["schemas"]["ErrorResponse"];
1533
- };
1534
- };
1535
- };
1536
- };
1537
- put?: never;
1538
- post?: never;
1539
- delete?: never;
1540
- options?: never;
1541
- head?: never;
1542
- patch?: never;
1543
- trace?: never;
1544
- };
1545
- "/resources/{id}/anchored-text": {
1546
- parameters: {
1547
- query?: never;
1548
- header?: never;
1549
- path?: never;
1550
- cookie?: never;
1551
- };
1552
- /**
1553
- * Get a resource's anchored text
1554
- * @description The coordinate map derived from a resource's bytes: its recovered text plus the positioned runs that index it. Assembled via the bus gateway.
1555
- *
1556
- * Whole-resource, not paginated — a producer iterates page by page, but every consumer wants one map: a browser quoting the text under a hand-drawn rectangle, a headless client analysing a document.
1557
- *
1558
- * This endpoint never runs recognition. The Smelter is the sole producer and publishes at ingest; a read that finds nothing waits for that resource's content generation to settle and then answers 204. A 204 is the common case and not an error — a native text layer is read in the browser, and a media type with no extractor never produces a map at all. Callers degrade: for a PDF annotation that means geometry with no quoted text.
1559
- */
1560
- get: {
1561
- parameters: {
1562
- query?: never;
1563
- header?: never;
1564
- path: {
1565
- id: string;
1566
- };
1567
- cookie?: never;
1568
- };
1569
- requestBody?: never;
1570
- responses: {
1571
- /** @description The stored extraction outcome: the coordinate map with its provenance (method, PDF class, OCR confidence, unread pages), or a named decline. */
1572
- 200: {
1573
- headers: {
1574
- [name: string]: unknown;
1575
- };
1576
- content: {
1577
- "application/json": components["schemas"]["ExtractionOutcome"];
1578
- };
1579
- };
1580
- /** @description No map has been derived for this resource. The ordinary answer for a native text layer or a media type with no extractor — not an error, and distinct from 404, which means the resource itself is absent. Carried as an empty body rather than a JSON `null` body so that a generated client's typed 200 field stays absent: unmarshalling `null` into a struct is a no-op in several languages, which would make "no map" indistinguishable from an empty one. */
1581
- 204: {
1582
- headers: {
1583
- [name: string]: unknown;
1584
- };
1585
- content?: never;
1586
- };
1587
- /** @description Resource not found */
1588
- 404: {
1589
- headers: {
1590
- [name: string]: unknown;
1591
- };
1592
- content: {
1593
- "application/json": components["schemas"]["ErrorResponse"];
1594
- };
1595
- };
1596
- /** @description Request timed out (bus gateway) */
1597
- 504: {
1598
- headers: {
1599
- [name: string]: unknown;
1600
- };
1601
- content: {
1602
- "application/json": components["schemas"]["ErrorResponse"];
1603
- };
1604
- };
1605
- };
1606
- };
1607
- put?: never;
1608
- post?: never;
1609
- delete?: never;
1610
- options?: never;
1611
- head?: never;
1612
- patch?: never;
1613
- trace?: never;
1614
- };
1615
- "/anchored-text/keys": {
1616
- parameters: {
1617
- query?: never;
1618
- header?: never;
1619
- path?: never;
1620
- cookie?: never;
1621
- };
1622
- /**
1623
- * List the keys under which anchored text is currently stored
1624
- * @description The anchored-text store's would-hit keys — the reconcile planner's bulk existence read (PERSIST-ANCHORS P0). The Smelter diffs this against the catalog to find resources whose derived coordinate map was lost (a transient store, a failed publish) and plans re-derivation; one request per reconcile, keys only, because each map is ~32 KB per scanned page and only presence is being asked.
1625
- *
1626
- * Keys are resource ids today; after PERSIST-ANCHORS P1 they are content checksums. Only entries a read would actually serve are listed — stale-stamped or unreadable entries are excluded, exactly as a read would exclude them.
1627
- *
1628
- * Agents only: this is projection-maintenance planning data, same trust boundary as publishing a map.
1629
- */
1630
- get: {
1631
- parameters: {
1632
- query?: never;
1633
- header?: never;
1634
- path?: never;
1635
- cookie?: never;
1156
+ /** @description Where the content lives (file://... for local). Required — the client names the location; the server does not derive one. */
1157
+ storageUri: string;
1158
+ /** @description ISO 639-1 language code */
1159
+ language?: string;
1160
+ /** @description JSON-stringified array of entity type names */
1161
+ entityTypes?: string;
1162
+ /** @description For AI-generated resources: the annotation that triggered generation. Nested into generatedFrom.annotationId on the persisted event. */
1163
+ sourceAnnotationId?: string;
1164
+ /** @description For AI-generated resources: the source resource the generating annotation lives on. Nested into generatedFrom.resourceId on the persisted event. */
1165
+ sourceResourceId?: string;
1166
+ /** @description For AI-generated resources: the prompt that drove generation */
1167
+ generationPrompt?: string;
1168
+ /** @description For AI-generated resources: JSON-stringified Agent (single object or array), capturing which model/worker produced the content */
1169
+ generator?: string;
1170
+ /** @description 'true' or 'false' — whether the resource is a draft */
1171
+ isDraft?: string;
1172
+ };
1173
+ };
1636
1174
  };
1637
- requestBody?: never;
1638
1175
  responses: {
1639
- /** @description Every key under which anchored text would currently be served. */
1640
- 200: {
1176
+ /** @description Resource accepted for creation */
1177
+ 202: {
1641
1178
  headers: {
1642
1179
  [name: string]: unknown;
1643
1180
  };
1644
1181
  content: {
1645
- "application/json": {
1646
- keys: string[];
1647
- };
1182
+ "application/json": components["schemas"]["CreateResourceResponse"];
1648
1183
  };
1649
1184
  };
1650
- /** @description Caller is not an agent */
1651
- 403: {
1185
+ /** @description Missing required fields (name, file, format, or storageUri), or the format's base MIME type is not a SupportedMediaType. The error message names the offending type. */
1186
+ 400: {
1187
+ headers: {
1188
+ [name: string]: unknown;
1189
+ };
1190
+ content: {
1191
+ "application/json": components["schemas"]["ErrorResponse"];
1192
+ };
1193
+ };
1194
+ /** @description Authentication required */
1195
+ 401: {
1652
1196
  headers: {
1653
1197
  [name: string]: unknown;
1654
1198
  };
@@ -1658,15 +1202,13 @@ interface paths {
1658
1202
  };
1659
1203
  };
1660
1204
  };
1661
- put?: never;
1662
- post?: never;
1663
1205
  delete?: never;
1664
1206
  options?: never;
1665
1207
  head?: never;
1666
1208
  patch?: never;
1667
1209
  trace?: never;
1668
1210
  };
1669
- "/anchored-text/{checksum}": {
1211
+ "/resources/{id}": {
1670
1212
  parameters: {
1671
1213
  query?: never;
1672
1214
  header?: never;
@@ -1674,85 +1216,37 @@ interface paths {
1674
1216
  cookie?: never;
1675
1217
  };
1676
1218
  /**
1677
- * Read a representation's stored extraction outcome by content checksum
1678
- * @description The cache-consult read (PERSIST-ANCHORS P2c): the extraction seam asks "has this exact byte content already been extracted?" and every cache consumer runs out of process (the smelter worker, the detection workers), so the consult must cross the wire or the cache is write-only from exactly the processes it exists to serve.
1219
+ * Get a resource's stored representation (the pipe)
1220
+ * @description Returns the stored representation's bytes, verbatim, with the stored media type in Content-Type (`application/octet-stream` when the stored metadata carries none). The Accept header is never read: there is no content negotiation and no transcoding, so the served bytes always hash to the representation's registered checksum.
1679
1221
  *
1680
- * Checksum-addressed and barrier-free, deliberately: presence at this instant is the question, the same semantics as the keys listing. The read-your-writes settle barrier belongs to the resource-addressed reader (GET /resources/{id}/anchored-text), which resolves a mutable resource id through the view index; a caller holding the checksum already holds the content identity and needs no resolution and no wait.
1222
+ * The resource's JSON-LD description (descriptor + annotations + inbound entity references) lives at GET /resources/{id}/jsonld; every content response advertises it via a `Link: rel="describedby"` header.
1681
1223
  *
1682
- * Agents only projection-maintenance traffic, the same trust boundary as the PUT beside it.
1224
+ * Content is immutable (checksum-addressed), and this route is bearer-authenticated, so responses carry `Cache-Control: private, max-age=31536000, immutable`.
1683
1225
  */
1684
1226
  get: {
1685
1227
  parameters: {
1686
1228
  query?: never;
1687
1229
  header?: never;
1688
1230
  path: {
1689
- /** @description Hex SHA-256 checksum of the representation bytes. */
1690
- checksum: string;
1231
+ id: string;
1691
1232
  };
1692
1233
  cookie?: never;
1693
1234
  };
1694
1235
  requestBody?: never;
1695
1236
  responses: {
1696
- /** @description The stored extraction outcome — a success with provenance, or a cached decline. */
1237
+ /** @description The stored representation's bytes, verbatim */
1697
1238
  200: {
1698
1239
  headers: {
1240
+ /** @description `</resources/{id}/jsonld>; rel="describedby"; type="application/ld+json"` — where to dereference the resource's JSON-LD description */
1241
+ Link?: string;
1699
1242
  [name: string]: unknown;
1700
1243
  };
1701
1244
  content: {
1702
- "application/json": components["schemas"]["ExtractionOutcome"];
1703
- };
1704
- };
1705
- /** @description No entry under this checksum. The ordinary cache miss — carried as an empty body rather than a JSON null for the same generated-client reason as the resource-addressed GET. */
1706
- 204: {
1707
- headers: {
1708
- [name: string]: unknown;
1709
- };
1710
- content?: never;
1711
- };
1712
- /** @description Caller is not an agent */
1713
- 403: {
1714
- headers: {
1715
- [name: string]: unknown;
1716
- };
1717
- content: {
1718
- "application/json": components["schemas"]["ErrorResponse"];
1719
- };
1720
- };
1721
- };
1722
- };
1723
- /**
1724
- * Publish anchored text for a representation, keyed by its content checksum
1725
- * @description Store the coordinate map derived from a representation's bytes, under the SHA-256 checksum of those bytes (PERSIST-ANCHORS decision A: one artifact per representation, and a representation is its bytes). The producer supplies the checksum because it alone knows which bytes it actually read — deriving the key server-side from the resource's current representation would file old geometry under a new checksum when a byte change races the publish, and that entry would read as present to the reconcile planner forever. Reads remain resource-addressed (GET /resources/{id}/anchored-text); the server resolves the resource to its current representation's checksum.
1726
- *
1727
- * The Smelter is the sole producer: it is the only process that reads those bytes at ingest, so it is the only one positioned to derive a map cheaply, and it runs separately from the backend.
1728
- *
1729
- * Agents only. A map is derived data every consumer trusts to place annotation geometry, so a browser session must not be able to write one.
1730
- */
1731
- put: {
1732
- parameters: {
1733
- query?: never;
1734
- header?: never;
1735
- path: {
1736
- /** @description Hex SHA-256 checksum of the representation bytes the map was derived from. */
1737
- checksum: string;
1738
- };
1739
- cookie?: never;
1740
- };
1741
- requestBody: {
1742
- content: {
1743
- "application/json": components["schemas"]["ExtractionOutcome"];
1744
- };
1745
- };
1746
- responses: {
1747
- /** @description Stored */
1748
- 204: {
1749
- headers: {
1750
- [name: string]: unknown;
1245
+ "*/*": string;
1751
1246
  };
1752
- content?: never;
1753
1247
  };
1754
- /** @description Body is not a valid ExtractionOutcome */
1755
- 400: {
1248
+ /** @description Resource or representation not found */
1249
+ 404: {
1756
1250
  headers: {
1757
1251
  [name: string]: unknown;
1758
1252
  };
@@ -1760,8 +1254,8 @@ interface paths {
1760
1254
  "application/json": components["schemas"]["ErrorResponse"];
1761
1255
  };
1762
1256
  };
1763
- /** @description Caller is not an agent */
1764
- 403: {
1257
+ /** @description Failed to retrieve resource */
1258
+ 500: {
1765
1259
  headers: {
1766
1260
  [name: string]: unknown;
1767
1261
  };
@@ -1771,6 +1265,7 @@ interface paths {
1771
1265
  };
1772
1266
  };
1773
1267
  };
1268
+ put?: never;
1774
1269
  post?: never;
1775
1270
  delete?: never;
1776
1271
  options?: never;
@@ -2356,6 +1851,11 @@ interface components {
2356
1851
  correlationId: string;
2357
1852
  response: Omit<components["schemas"]["ExtractionOutcome"], "kind"> | null;
2358
1853
  };
1854
+ /** @description Request the stored extraction outcome for a content identity the caller already holds — the detection workers' read-through cache consult (ANCHORED-TEXT-TO-SMELTER P2). A hit — success or decline — is served whole and the caller skips extraction; null is a miss and the caller extracts locally. Read-only: the Smelter is the sole writer and never answers over this channel. */
1855
+ BrowseAnchoredTextByChecksumRequest: {
1856
+ correlationId: string;
1857
+ checksum: string;
1858
+ };
2359
1859
  /** @description Request to browse a single resource */
2360
1860
  BrowseResourceRequest: {
2361
1861
  correlationId: string;
@@ -2407,7 +1907,7 @@ interface components {
2407
1907
  payload: {
2408
1908
  [key: string]: unknown;
2409
1909
  };
2410
- /** @description Optional resource scope for broadcast channels (e.g. resourceId). Publishers only — frontends must never set this. */
1910
+ /** @description Optional resource scope for broadcast channels (e.g. resourceId). Publishers only — clients must never set this. */
2411
1911
  scope?: string;
2412
1912
  };
2413
1913
  /** @description Subscription matrix for the bus SSE stream (MULTI-RESOURCE-SCOPE). `global` channels are delivered unscoped; each `scoped` entry subscribes the connection to one resource scope's channels, optionally resuming replay from that scope's last-seen persisted event id. At least one global channel or one scoped entry is required. */
@@ -2542,7 +2042,7 @@ interface components {
2542
2042
  DiscoveredKB: {
2543
2043
  /** @description Hostname the KB is reachable on from this machine (today always "localhost" — local stacks bind locally and codespace KBs arrive through a local port forward) */
2544
2044
  host: string;
2545
- /** @description Local TCP port of the KB's API (the backend port for a local stack; the allocated forward port for a codespace stack) */
2045
+ /** @description Local TCP port of the KB's API (the gateway port for a local stack; the allocated forward port for a codespace stack) */
2546
2046
  port: number;
2547
2047
  /**
2548
2048
  * @description Where the stack actually runs. "local": containers on this machine. "codespace": a GitHub-hosted VM whose KB is port-forwarded here.
@@ -2560,7 +2060,7 @@ interface components {
2560
2060
  };
2561
2061
  /**
2562
2062
  * DiscoveryDocument
2563
- * @description The launcher's KB discovery document — the schema authority for <stateDir>/discovery/kbs.json, which the semiont launcher (Go, apps/launcher) regenerates on every stack mutation and the frontend container mounts read-only at /discovery. NOT an API endpoint: a static document fetched same-origin by browsers (via the frontend's static server) or read from disk by local Node consumers. An empty kbs list is meaningful ("the launcher manages nothing right now") and distinct from an absent file. Design record: .plans/BROWSER-KB-DISCOVERY.md.
2063
+ * @description The launcher's KB discovery document — the schema authority for <stateDir>/discovery/kbs.json, which the semiont launcher (Go, apps/launcher) regenerates on every stack mutation and the Browser container mounts read-only at /discovery. NOT an API endpoint: a static document fetched same-origin by browsers (via the Browser's static server) or read from disk by local Node consumers. An empty kbs list is meaningful ("the launcher manages nothing right now") and distinct from an absent file. Design record: .plans/BROWSER-KB-DISCOVERY.md.
2564
2064
  */
2565
2065
  DiscoveryDocument: {
2566
2066
  /**
@@ -2849,9 +2349,9 @@ interface components {
2849
2349
  };
2850
2350
  /** @description Params bag for `job:create` with `jobType: 'generation'` — exactly the shape yield.fromContext(context, options) takes: options + the gathered context. The job's ids are DERIVED from context.focus at the dispatcher (resource focus → focus.resource; annotation focus → focus.sourceResource, with the worker auto-binding to focus.annotation); a caller-supplied referenceId is rejected. Carried inside JobCreateCommand.params; this schema is the generation shape's contract, including its requiredness. */
2851
2351
  GenerationJobParams: {
2852
- /** @description Title of the generated resource. */
2352
+ /** @description Title of the generated resource. Non-empty: the dispatcher and worker both reject an empty title via isGenerationJobParams. NOTE minLength is documentation here — JobCreateCommand.params is additionalProperties:true, so /bus/emit's generated validator never sees this field (GENERATION-OUTPUT-FORMAT D9b). */
2853
2353
  title: string;
2854
- /** @description Storage URI for the generated resource's content. */
2354
+ /** @description Storage URI for the generated resource's content — AUTHORITATIVE: the worker writes exactly here and never derives a location from the title. Non-empty, and there is no fallback; the dispatcher and worker both reject an empty value via isGenerationJobParams. NOTE minLength is documentation here — JobCreateCommand.params is additionalProperties:true, so /bus/emit's generated validator never sees this field (GENERATION-OUTPUT-FORMAT D6/D9). */
2855
2355
  storageUri: string;
2856
2356
  /** @description The gathered context that grounds the generation. Its `focus` names the anchor: the DISPATCHER derives the job's resourceId from it (resource focus → focus.resource; annotation focus → focus.sourceResource, with the worker auto-binding to focus.annotation) and REJECTS a caller-supplied id — the context is authoritative. Under `cite`, the ids its embedding carries are the only valid citation targets. */
2857
2357
  context: components["schemas"]["GatheredContext"];
@@ -3091,7 +2591,7 @@ interface components {
3091
2591
  */
3092
2592
  declined: true;
3093
2593
  /**
3094
- * @description Why the resource could not be read. A CODE, not a sentence: the client owns the wording, so a browser renders it in the user's language and the CLI renders English terminal copy from the same value. The prose `message` this schema used to carry was composed backend-side and was therefore English everywhere (ASSIST-PROGRESS-CONSOLIDATION P5).
2594
+ * @description Why the resource could not be read. A CODE, not a sentence: the client owns the wording, so a browser renders it in the user's language and the CLI renders English terminal copy from the same value. The prose `message` this schema used to carry was composed gateway-side and was therefore English everywhere (ASSIST-PROGRESS-CONSOLIDATION P5).
3095
2595
  * @enum {string}
3096
2596
  */
3097
2597
  reason: "no-text-layer" | "encrypted" | "corrupt" | "too-large" | "empty";
@@ -3399,6 +2899,7 @@ interface components {
3399
2899
  /** @description Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this. */
3400
2900
  _userId?: string;
3401
2901
  resourceId: string;
2902
+ /** @description Optional: where the resource's bytes live, so the archive can act on the file. An instruction to this handler, not a copy of the stored fact (that lives on the primary Representation). Working-tree URI, only file:// is supported. */
3402
2903
  storageUri?: string;
3403
2904
  keepFile?: boolean;
3404
2905
  noGit?: boolean;
@@ -3487,6 +2988,7 @@ interface components {
3487
2988
  /** @description Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this. */
3488
2989
  _userId?: string;
3489
2990
  resourceId: string;
2991
+ /** @description Optional: where the resource's bytes are expected to be. When present the handler VERIFIES the file exists and fails loudly if it does not, rather than succeeding as a no-op. An instruction, not a copy of the stored fact (that lives on the primary Representation). Working-tree URI, only file:// is supported. */
3490
2992
  storageUri?: string;
3491
2993
  };
3492
2994
  /** @description Bus command to update an annotation's body with patch operations. */
@@ -3578,7 +3080,7 @@ interface components {
3578
3080
  "@type"?: string | string[];
3579
3081
  /** @description MIME/media type (e.g., text/markdown, image/png). */
3580
3082
  mediaType: string;
3581
- /** @description Working-tree URI identifying where the bytes live. Only file:// is supported (e.g. file://docs/overview.md). */
3083
+ /** @description Working-tree URI identifying where this rendition's bytes live. Only file:// is supported (e.g. file://docs/overview.md). The single home of the storage location: maintained across moves (yield:moved relocates it), absent when the resource has no stored bytes. */
3582
3084
  storageUri?: string;
3583
3085
  filename?: string;
3584
3086
  /** @description Size of the payload in bytes. */
@@ -3629,6 +3131,8 @@ interface components {
3629
3131
  format: components["schemas"]["ContentFormat"];
3630
3132
  contentChecksum: string;
3631
3133
  contentByteSize?: number;
3134
+ /** @description Where the clone's bytes are, on the resource's primary Representation — the same single home `yield:created` writes to (STORAGE-URI-ONE-HOME). */
3135
+ storageUri?: string;
3632
3136
  parentResourceId: string;
3633
3137
  entityTypes?: string[];
3634
3138
  language?: string;
@@ -3641,7 +3145,7 @@ interface components {
3641
3145
  contentChecksum: string;
3642
3146
  contentByteSize?: number;
3643
3147
  entityTypes?: string[];
3644
- /** @description Working-tree URI (e.g. file://docs/overview.md) */
3148
+ /** @description The creating instruction's URI, recorded on the event. Append-only, so this value never changes — the LOCATION the projection serves is maintained across moves and lives on the resource's primary Representation, relocated by yield:moved. Optional: a resource may have no bytes. Working-tree URI, only file:// is supported (e.g. file://docs/overview.md). */
3645
3149
  storageUri?: string;
3646
3150
  language?: string;
3647
3151
  isDraft?: boolean;
@@ -3715,10 +3219,6 @@ interface components {
3715
3219
  * @description Original URI from a source knowledge base when this resource was imported
3716
3220
  */
3717
3221
  originatedFrom?: string;
3718
- /** @description Working-tree URI for this resource (e.g. file://docs/overview.md). Stable across updates and moves. */
3719
- storageUri?: string;
3720
- /** @description SHA-256 hex hash of the current content. Updated on resource.created, resource.updated, resource.cloned events. */
3721
- currentChecksum?: string;
3722
3222
  } & {
3723
3223
  [key: string]: unknown;
3724
3224
  };
@@ -3831,7 +3331,7 @@ interface components {
3831
3331
  projectName?: string;
3832
3332
  /** @description Current git branch of the knowledge base repository */
3833
3333
  gitBranch?: string;
3834
- /** @description The knowledge base's did:web identity — 'did:web:' + the committed [site] domain, byte-identical to the string the launcher publishes in its discovery document. REQUIRED: a KB that declares no domain does not run (the launcher refuses to start it, and the backend refuses to boot), so a response without this field means the caller reached something that bypassed both. Identifies WHICH knowledge base this is; it does NOT identify which running copy — one KB reachable at two addresses (a local clone and a codespace of one repo) reports the same did at both. Use it to verify what you connected to, not to select among discovered entries. */
3334
+ /** @description The knowledge base's did:web identity — 'did:web:' + the committed [site] domain, byte-identical to the string the launcher publishes in its discovery document. REQUIRED: a KB that declares no domain does not run (the launcher refuses to start it, and the gateway refuses to boot), so a response without this field means the caller reached something that bypassed both. Identifies WHICH knowledge base this is; it does NOT identify which running copy — one KB reachable at two addresses (a local clone and a codespace of one repo) reports the same did at both. Use it to verify what you connected to, not to select among discovered entries. */
3835
3335
  did: string;
3836
3336
  };
3837
3337
  /** @description A persisted domain event with metadata. Flat shape — event fields and metadata are peers. */
@@ -3988,14 +3488,18 @@ interface components {
3988
3488
  /** @description Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this. */
3989
3489
  _userId?: string;
3990
3490
  };
3991
- /** @description Bus command to create a cloned resource from a clone token. */
3491
+ /** @description Bus command to create a cloned resource from a clone token. Bytes are stored gateway-side BEFORE this command is emitted (GATEWAY.md D4a: the Archivist serves no bytes) — the command carries the storage coordinates, never content. */
3992
3492
  YieldCloneCreateCommand: {
3993
3493
  correlationId: string;
3994
3494
  /** @description Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this. */
3995
3495
  _userId?: string;
3996
3496
  token: string;
3997
3497
  name: string;
3998
- content: string;
3498
+ /** @description Where the caller already wrote the clone's bytes — an instruction, not a copy of the stored fact (that lives on the primary Representation). Bytes are stored through the byte door BEFORE this command is sent, so this names an existing file. Working-tree URI, only file:// is supported. */
3499
+ storageUri: string;
3500
+ contentChecksum: string;
3501
+ byteSize: number;
3502
+ format: components["schemas"]["ContentFormat"];
3999
3503
  archiveOriginal?: boolean;
4000
3504
  };
4001
3505
  /** @description Success response after creating a cloned resource. */
@@ -4022,6 +3526,7 @@ interface components {
4022
3526
  /** @description Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this. */
4023
3527
  _userId?: string;
4024
3528
  name: string;
3529
+ /** @description The caller's instruction for WHERE the bytes are — not a copy of the stored fact. The stored location lives on the resource's primary Representation (`Representation.storageUri`), which is its single home; this field is the message that puts it there. Working-tree URI, only file:// is supported (e.g. file://docs/overview.md). */
4025
3530
  storageUri: string;
4026
3531
  contentChecksum: string;
4027
3532
  byteSize: number;
@@ -4037,6 +3542,34 @@ interface components {
4037
3542
  generator?: components["schemas"]["Agent"] | components["schemas"]["Agent"][];
4038
3543
  noGit?: boolean;
4039
3544
  };
3545
+ /**
3546
+ * @description Command: stow an already-uploaded clone's bytes and append `yield:cloned`.
3547
+ *
3548
+ * The INNER half of the clone flow. `yield:clone-create` reaches the CloneTokenManager, which alone can validate the token and read the source's entity types; it then emits this so the Stower — the only appendEvent caller — writes the domain event.
3549
+ *
3550
+ * Distinct from `yield:create` because a clone is a distinct operation, not a creation with an extra field. It REQUIRES a parent, and that requirement is what a separate command expresses: an optional `parentResourceId` on the create command could not say that a clone without a parent is not a clone. `ResourceClonedPayload` requires it for the same reason.
3551
+ *
3552
+ * Generated resources are NOT clones: they carry provenance in `generatedFrom` and stay on `yield:create`.
3553
+ */
3554
+ YieldClonePersistCommand: {
3555
+ /** @description Correlation id so busRequest can match the reply. */
3556
+ correlationId: string;
3557
+ /** @description Injected by the gateway from the authenticated principal; never supplied by a wire caller. */
3558
+ _userId?: string;
3559
+ name: string;
3560
+ /** @description The caller's instruction for WHERE the bytes are — the uploader wrote them before emitting this. The stored location lives on the clone's primary Representation (STORAGE-URI-ONE-HOME). */
3561
+ storageUri: string;
3562
+ contentChecksum: string;
3563
+ byteSize: number;
3564
+ format: components["schemas"]["ContentFormat"];
3565
+ language?: string;
3566
+ /** @description Inherited from the source resource by the CloneTokenManager, which is the only party that knows the token is valid. */
3567
+ entityTypes?: string[];
3568
+ /** @description The resource this one is cloned FROM. Required: it is what makes this a clone rather than a creation. */
3569
+ parentResourceId: string;
3570
+ /** @description The bytes were already written by the uploader; the Stower's register does the one `git add` on apply (GATEWAY.md D4b). */
3571
+ noGit?: boolean;
3572
+ };
4040
3573
  /** @description Success reply after creating a yielded resource, matched to the originating command by correlationId. */
4041
3574
  YieldCreateOk: {
4042
3575
  /** @description Correlation id echoed from the yield:create command so busRequest can match the reply. */
@@ -4046,6 +3579,15 @@ interface components {
4046
3579
  resourceId: string;
4047
3580
  };
4048
3581
  };
3582
+ /** @description Success reply after cloning a resource, matched to the originating command by correlationId. */
3583
+ YieldClonePersistOk: {
3584
+ /** @description Correlation id echoed from the yield:clone-persist command so busRequest can match the reply. */
3585
+ correlationId?: string;
3586
+ /** @description The clone's identity — a new resource, distinct from its parent. */
3587
+ response: {
3588
+ resourceId: string;
3589
+ };
3590
+ };
4049
3591
  /** @description Bus command to move (rename) a yielded resource. */
4050
3592
  YieldMvCommand: {
4051
3593
  /** @description Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this. */
@@ -4061,6 +3603,7 @@ interface components {
4061
3603
  /** @description Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this. */
4062
3604
  _userId?: string;
4063
3605
  resourceId: string;
3606
+ /** @description The caller's instruction for WHERE the bytes are — not a copy of the stored fact. The stored location lives on the resource's primary Representation (`Representation.storageUri`), which is its single home; this field is the message that puts it there. Working-tree URI, only file:// is supported (e.g. file://docs/overview.md). */
4064
3607
  storageUri: string;
4065
3608
  contentChecksum: string;
4066
3609
  byteSize: number;
@@ -4408,7 +3951,7 @@ interface AnchorRect {
4408
3951
  *
4409
3952
  * The complete EventMap for the RxJS EventBus. Every channel name and
4410
3953
  * its payload type is defined here — domain events, commands, reads,
4411
- * results, SSE stream payloads, and frontend UI events.
3954
+ * results, SSE stream payloads, and Browser UI events.
4412
3955
  *
4413
3956
  * Identifier discipline: where a payload carries an annotation or
4414
3957
  * resource id, the TypeScript layer narrows the OpenAPI `string` to the
@@ -4454,6 +3997,7 @@ type EventMap = {
4454
3997
  'yield:representation-added': StoredEvent<EventOfType<'yield:representation-added'>>;
4455
3998
  'yield:representation-removed': StoredEvent<EventOfType<'yield:representation-removed'>>;
4456
3999
  'yield:create': components['schemas']['YieldCreateCommand'];
4000
+ 'yield:clone-persist': components['schemas']['YieldClonePersistCommand'];
4457
4001
  'yield:update': components['schemas']['YieldUpdateCommand'];
4458
4002
  'yield:mv': components['schemas']['YieldMvCommand'];
4459
4003
  'yield:clone': void;
@@ -4462,6 +4006,10 @@ type EventMap = {
4462
4006
  'yield:clone-create': components['schemas']['YieldCloneCreateCommand'];
4463
4007
  'yield:create-ok': components['schemas']['YieldCreateOk'];
4464
4008
  'yield:create-failed': components['schemas']['CommandError'];
4009
+ 'yield:clone-persist-ok': components['schemas']['YieldClonePersistOk'];
4010
+ 'yield:clone-persist-failed': {
4011
+ correlationId: string;
4012
+ } & components['schemas']['CommandError'];
4465
4013
  'yield:update-ok': components['schemas']['YieldUpdateOk'];
4466
4014
  'yield:update-failed': components['schemas']['CommandError'];
4467
4015
  'yield:move-failed': {
@@ -4601,6 +4149,14 @@ type EventMap = {
4601
4149
  'browse:anchored-text-failed': {
4602
4150
  correlationId: string;
4603
4151
  } & components['schemas']['CommandError'];
4152
+ 'browse:anchored-text-by-checksum-requested': components['schemas']['BrowseAnchoredTextByChecksumRequest'];
4153
+ 'browse:anchored-text-by-checksum-result': {
4154
+ correlationId: string;
4155
+ response: components['schemas']['ExtractionOutcome'] | null;
4156
+ };
4157
+ 'browse:anchored-text-by-checksum-failed': {
4158
+ correlationId: string;
4159
+ } & components['schemas']['CommandError'];
4604
4160
  'browse:resources-requested': components['schemas']['BrowseResourcesRequest'];
4605
4161
  'browse:resources-result': {
4606
4162
  correlationId: string;
@@ -4737,7 +4293,7 @@ type EventMap = {
4737
4293
  * Emitted by the Weaver after applying an event (or a batch's last event)
4738
4294
  * for a resource to the graph. `sequenceNumber` is the resource-stream
4739
4295
  * sequence of the last applied event. Folded by `WeaveProgress`
4740
- * (make-meaning) into the backend-local applied map that the
4296
+ * (make-meaning) into the gateway-local applied map that the
4741
4297
  * `whenApplied` barrier awaits. In-process signal today; crosses the
4742
4298
  * bus gateway after WEAVER-ISOLATION.
4743
4299
  */
@@ -4867,6 +4423,7 @@ declare const CHANNEL_SCHEMAS: {
4867
4423
  readonly 'yield:representation-added': null;
4868
4424
  readonly 'yield:representation-removed': null;
4869
4425
  readonly 'yield:create': "YieldCreateCommand";
4426
+ readonly 'yield:clone-persist': "YieldClonePersistCommand";
4870
4427
  readonly 'yield:update': "YieldUpdateCommand";
4871
4428
  readonly 'yield:mv': "YieldMvCommand";
4872
4429
  readonly 'yield:clone': null;
@@ -4875,6 +4432,8 @@ declare const CHANNEL_SCHEMAS: {
4875
4432
  readonly 'yield:clone-create': "YieldCloneCreateCommand";
4876
4433
  readonly 'yield:create-ok': "YieldCreateOk";
4877
4434
  readonly 'yield:create-failed': "CommandError";
4435
+ readonly 'yield:clone-persist-ok': "YieldClonePersistOk";
4436
+ readonly 'yield:clone-persist-failed': null;
4878
4437
  readonly 'yield:update-ok': "YieldUpdateOk";
4879
4438
  readonly 'yield:update-failed': null;
4880
4439
  readonly 'yield:move-failed': null;
@@ -4953,6 +4512,9 @@ declare const CHANNEL_SCHEMAS: {
4953
4512
  readonly 'browse:anchored-text-requested': "BrowseAnchoredTextRequest";
4954
4513
  readonly 'browse:anchored-text-result': "BrowseAnchoredTextResult";
4955
4514
  readonly 'browse:anchored-text-failed': null;
4515
+ readonly 'browse:anchored-text-by-checksum-requested': "BrowseAnchoredTextByChecksumRequest";
4516
+ readonly 'browse:anchored-text-by-checksum-result': "BrowseAnchoredTextResult";
4517
+ readonly 'browse:anchored-text-by-checksum-failed': null;
4956
4518
  readonly 'browse:resources-requested': "BrowseResourcesRequest";
4957
4519
  readonly 'browse:resources-result': "BrowseResourcesResult";
4958
4520
  readonly 'browse:resources-failed': null;
@@ -5198,6 +4760,13 @@ declare class EventBus {
5198
4760
  * using runtime `PersistedEventType` strings.
5199
4761
  */
5200
4762
  getDomainEvent(eventType: PersistedEventType): Subject<StoredEvent>;
4763
+ /**
4764
+ * Channel names with at least one live observer right now. Introspection
4765
+ * for composition-parity gates: `get()` creates subjects lazily, so mere
4766
+ * access does not count — only real subscriptions do. Scoped channels
4767
+ * appear under their namespaced key (`<scope>:<channel>`).
4768
+ */
4769
+ observedChannels(): string[];
5201
4770
  /**
5202
4771
  * Destroy the event bus and complete all subjects
5203
4772
  *
@@ -5434,7 +5003,7 @@ declare function errField(error: unknown): unknown;
5434
5003
  * Bus logging — runtime-toggleable cross-wire visibility.
5435
5004
  *
5436
5005
  * One line per event that crosses a process boundary, in a grep-able
5437
- * format that's symmetric across frontend and backend:
5006
+ * format that's symmetric across frontend and gateway:
5438
5007
  *
5439
5008
  * [bus EMIT] <channel> [scope=X] [cid=<first8>] <payload>
5440
5009
  * [bus RECV] <channel> [scope=X] [cid=<first8>] <payload>
@@ -5924,7 +5493,11 @@ declare function getChecksum(resource: ResourceDescriptor | undefined): string |
5924
5493
  */
5925
5494
  declare function getLanguage(resource: ResourceDescriptor | undefined): string | undefined;
5926
5495
  /**
5927
- * Get storage URI from primary representation
5496
+ * Get the storage URI from the primary representation — the field's ONE home
5497
+ * (STORAGE-URI-ONE-HOME): bytes are a fact about a rendition, so their
5498
+ * location lives on the Representation, never on the descriptor. This is the
5499
+ * accessor every descriptor-holding read goes through; `undefined` means the
5500
+ * resource has no stored bytes.
5928
5501
  *
5929
5502
  * @param resource - ResourceDescriptor
5930
5503
  * @returns Storage URI or undefined
@@ -6014,7 +5587,7 @@ declare function decodeRepresentation(buffer: Buffer, mediaType: string): string
6014
5587
  * - `not-found` — resource missing (HTTP 404)
6015
5588
  * - `conflict` — concurrent modification, duplicate, etc. (HTTP 409)
6016
5589
  * - `bad-request` — request malformed (HTTP 400)
6017
- * - `unavailable` — backend unreachable, network error, 5xx
5590
+ * - `unavailable` — gateway unreachable, network error, 5xx
6018
5591
  * - `error` — unclassified fallback
6019
5592
  */
6020
5593
  type TransportErrorCode = 'unauthorized' | 'forbidden' | 'not-found' | 'conflict' | 'bad-request' | 'unavailable' | 'error';
@@ -6050,11 +5623,11 @@ declare class ConflictError extends SemiontError {
6050
5623
  *
6051
5624
  * ITransport — bus primitives + lifecycle. Universal: every
6052
5625
  * concrete transport implements this.
6053
- * IBackendOperations — auth, admin, exchange, system endpoints.
5626
+ * IGatewayOperations — auth, admin, and system endpoints.
6054
5627
  * HTTP-shaped today; an in-process transport may
6055
5628
  * implement none, some, or a different set.
6056
5629
  * Optional on `SemiontClient` — passed only when
6057
- * the host has a backend that supports them.
5630
+ * the host has a gateway that supports them.
6058
5631
  * IContentTransport — binary I/O (putBinary / getBinary). Narrow by
6059
5632
  * design because binary has different backpressure
6060
5633
  * and streaming characteristics.
@@ -6123,27 +5696,6 @@ type UserResponse = ResponseContent<paths['/api/users/me']['get']>;
6123
5696
  type UpdateUserRequest = RequestContent<paths['/api/admin/users/{id}']['patch']>;
6124
5697
  type UpdateUserResponse = ResponseContent<paths['/api/admin/users/{id}']['patch']>;
6125
5698
  type ListUsersResponse = ResponseContent<paths['/api/admin/users']['get']>;
6126
- type ProgressEvent = {
6127
- phase: string;
6128
- message?: string;
6129
- result?: Record<string, unknown>;
6130
- };
6131
- type ProgressCallback = (event: ProgressEvent) => void;
6132
- /**
6133
- * Stream-shaped return type for backend download operations
6134
- * (`backupKnowledgeBase`, `exportKnowledgeBase`). Transport-neutral —
6135
- * any implementation can produce a `ReadableStream<Uint8Array>` without
6136
- * fabricating a fetch `Response`. HTTP wraps `response.body` and
6137
- * `response.headers`; in-process implementations return their own stream.
6138
- *
6139
- * The same shape `IContentTransport.getBinaryStream` already uses for
6140
- * binary downloads.
6141
- */
6142
- interface BackendDownload {
6143
- stream: ReadableStream<Uint8Array>;
6144
- contentType: string;
6145
- filename?: string;
6146
- }
6147
5699
  interface ITransport {
6148
5700
  /**
6149
5701
  * Base URL the transport speaks to. For HTTP this is `https://host[:port]`;
@@ -6159,7 +5711,7 @@ interface ITransport {
6159
5711
  *
6160
5712
  * Resolves with the number of subscribers the emit reached
6161
5713
  * (`/bus/emit` responds `{subscribers: n}`; GUIDED-TOUR P1), or `-1`
6162
- * when the count is unknown — an older backend, an unreadable body, or
5714
+ * when the count is unknown — an older gateway, an unreadable body, or
6163
5715
  * an in-process transport where the question does not apply. `-1` is
6164
5716
  * the same sentinel the Go client uses: a parse failure must stay
6165
5717
  * distinguishable from a genuine empty room.
@@ -6228,9 +5780,9 @@ interface ITransport {
6228
5780
  dispose(): void;
6229
5781
  }
6230
5782
  /**
6231
- * Auth, admin, exchange, and system endpoints. HTTP-shaped today —
5783
+ * Auth, admin, and system endpoints. HTTP-shaped today —
6232
5784
  * `HttpTransport` implements both this and `ITransport`; the
6233
- * `SemiontClient` constructor takes a `IBackendOperations` argument
5785
+ * `SemiontClient` constructor takes a `IGatewayOperations` argument
6234
5786
  * separately from the bus transport so non-HTTP transports
6235
5787
  * (`LocalTransport`) can implement just the bus surface and the
6236
5788
  * SemiontClient cleanly omits `client.auth` / `client.admin`.
@@ -6239,7 +5791,7 @@ interface ITransport {
6239
5791
  * `TransportErrorCode` (see `errors.ts`) so the routing layer
6240
5792
  * (`SemiontBrowser`) stays transport-neutral.
6241
5793
  */
6242
- interface IBackendOperations {
5794
+ interface IGatewayOperations {
6243
5795
  authenticatePassword(email: Email, password: string): Promise<AuthResponse>;
6244
5796
  authenticateGoogle(credential: GoogleCredential): Promise<AuthResponse>;
6245
5797
  refreshAccessToken(token: RefreshToken): Promise<TokenRefreshResponse>;
@@ -6253,22 +5805,6 @@ interface IBackendOperations {
6253
5805
  getUserStats(): Promise<AdminUserStatsResponse>;
6254
5806
  updateUser(id: UserDID, data: UpdateUserRequest): Promise<UpdateUserResponse>;
6255
5807
  getOAuthConfig(): Promise<OAuthConfigResponse>;
6256
- backupKnowledgeBase(): Promise<BackendDownload>;
6257
- /**
6258
- * Stream of `ProgressEvent`s for a restore/import operation. The
6259
- * Observable emits each progress event in order and completes when
6260
- * the operation is done; the final event carries `phase: 'complete'`
6261
- * (or `'error'` / `'failed'` followed by an Observable error).
6262
- *
6263
- * The SDK wraps the contract's `Observable<ProgressEvent>` as a
6264
- * `StreamObservable<ProgressEvent>` so consumers can `await` for the
6265
- * final event or `.subscribe(...)` to render every step.
6266
- */
6267
- restoreKnowledgeBase(file: File): Observable<ProgressEvent>;
6268
- exportKnowledgeBase(params?: {
6269
- includeArchived?: boolean;
6270
- }): Promise<BackendDownload>;
6271
- importKnowledgeBase(file: File): Observable<ProgressEvent>;
6272
5808
  healthCheck(): Promise<HealthCheckResponse>;
6273
5809
  getStatus(): Promise<StatusResponse>;
6274
5810
  }
@@ -6284,6 +5820,15 @@ interface PutBinaryRequest {
6284
5820
  generationPrompt?: string;
6285
5821
  generator?: Agent$1 | Agent$1[];
6286
5822
  isDraft?: boolean;
5823
+ /**
5824
+ * Clone provenance (EXTRACT-ARCHIVIST P3): when set, the gateway stores
5825
+ * the bytes and routes creation through `yield:clone-create` — the
5826
+ * CloneTokenManager validates the token and inherits source metadata.
5827
+ * Bytes never ride the bus (D4a).
5828
+ */
5829
+ cloneToken?: string;
5830
+ /** Clone-only: archive the source resource after a successful clone. */
5831
+ archiveOriginal?: boolean;
6287
5832
  }
6288
5833
  /**
6289
5834
  * Optional byte-progress hook for `putBinary`. Receives raw byte counts;
@@ -6339,85 +5884,6 @@ interface IContentTransport {
6339
5884
  getResourceGraph(resourceId: ResourceId, options?: {
6340
5885
  auth?: AccessToken;
6341
5886
  }): Promise<GetResourceResponse>;
6342
- /**
6343
- * Store anchored text — the coordinate map a producer derived from a
6344
- * representation's bytes (OCR, a native text layer, a table or form
6345
- * reader) — under **the content checksum of those bytes** (PERSIST-ANCHORS
6346
- * decision A: one artifact per representation, and a representation IS its
6347
- * bytes).
6348
- *
6349
- * The producer supplies the checksum because it alone knows which bytes it
6350
- * actually read. That is a correctness rule, not a convenience: if the
6351
- * store derived the key from the resource's CURRENT representation at
6352
- * write time, a byte change racing the publish would file old geometry
6353
- * under the new checksum — wrong quotes served, and the reconcile diff
6354
- * sees "artifact present" so it never heals. Producer-supplied, the same
6355
- * race files the map under the OLD checksum: an unreachable orphan, and
6356
- * the new checksum's missing artifact is exactly what the third drift
6357
- * class re-derives (SMELTER-AXIOMS S15).
6358
- *
6359
- * Its own method rather than a `putBinary` of some derived media type: a
6360
- * coordinate map is not a *representation* of the resource, and dressing it
6361
- * as one would make a derived artifact indistinguishable from content a user
6362
- * uploaded.
6363
- *
6364
- * Whole-representation, like `getResourceGraph` is whole-resource. The
6365
- * producer iterates page by page; every consumer wants one map.
6366
- */
6367
- putAnchoredText(checksum: string, outcome: ExtractionOutcome, options?: {
6368
- auth?: AccessToken;
6369
- }): Promise<void>;
6370
- /**
6371
- * The resource's anchored text, or `null` when none has been derived.
6372
- *
6373
- * Deliberately resource-addressed while `putAnchoredText` is
6374
- * checksum-addressed: readers hold a resource id, and the server resolves
6375
- * it to the current representation's checksum through the view — the
6376
- * `resourceId → checksum` index of PERSIST-ANCHORS decision A. A reader
6377
- * therefore can never receive geometry for bytes the resource no longer
6378
- * has: the pointer moves, the artifacts stay, the index always follows
6379
- * the pointer.
6380
- *
6381
- * `null` is not an error and is the common case: a native text layer is read
6382
- * in the browser, and a resource whose media type has no extractor never
6383
- * produces a map at all. Callers degrade — for a PDF annotation that means
6384
- * geometry with no quoted text, which is the behaviour that shipped before
6385
- * any of this existed.
6386
- */
6387
- getAnchoredText(resourceId: ResourceId, options?: {
6388
- auth?: AccessToken;
6389
- }): Promise<ExtractionOutcome | null>;
6390
- /**
6391
- * The stored extraction outcome for exactly this byte content, or `null`
6392
- * for a miss — the cache-consult read (PERSIST-ANCHORS P2c). Every cache
6393
- * consumer runs out of process (the smelter worker, the detection
6394
- * workers), so the `extract()` seam's consult crosses the wire through
6395
- * this method; without it the cache would be write-only from exactly the
6396
- * processes it exists to serve.
6397
- *
6398
- * Checksum-addressed and barrier-free, unlike `getAnchoredText`:
6399
- * presence at this instant is the question (the keys listing's
6400
- * semantics), and a caller holding the checksum already holds the
6401
- * content identity — nothing to resolve, nothing to wait for.
6402
- */
6403
- getAnchoredTextByChecksum(checksum: string, options?: {
6404
- auth?: AccessToken;
6405
- }): Promise<ExtractionOutcome | null>;
6406
- /**
6407
- * Every key under which anchored text would currently be served — the
6408
- * reconcile planner's bulk existence read (PERSIST-ANCHORS P0). The
6409
- * Smelter diffs this against the catalog to find resources whose artifact
6410
- * was lost (a transient store, a failed publish) and plans re-derivation;
6411
- * one call per reconcile, never a `getAnchoredText` probe per resource,
6412
- * because each map is ~32 KB per scanned page and only presence is asked.
6413
- *
6414
- * Keys are resource ids today; after PERSIST-ANCHORS P1 they are content
6415
- * checksums. Callers compare against whichever handle the store is keyed
6416
- * by — the diff moves with the rekey, this contract does not.
6417
- */
6418
- listAnchoredTextKeys(options?: {
6419
- auth?: AccessToken;
6420
- }): Promise<string[]>;
6421
5887
  dispose(): void;
6422
5888
  }
6423
5889
 
@@ -6461,6 +5927,10 @@ declare const BUS_OPERATIONS: {
6461
5927
  readonly result: "browse:anchored-text-result";
6462
5928
  readonly failure: "browse:anchored-text-failed";
6463
5929
  };
5930
+ readonly 'browse:anchored-text-by-checksum-requested': {
5931
+ readonly result: "browse:anchored-text-by-checksum-result";
5932
+ readonly failure: "browse:anchored-text-by-checksum-failed";
5933
+ };
6464
5934
  readonly 'browse:resources-requested': {
6465
5935
  readonly result: "browse:resources-result";
6466
5936
  readonly failure: "browse:resources-failed";
@@ -6578,6 +6048,10 @@ declare const BUS_OPERATIONS: {
6578
6048
  readonly result: "yield:create-ok";
6579
6049
  readonly failure: "yield:create-failed";
6580
6050
  };
6051
+ readonly 'yield:clone-persist': {
6052
+ readonly result: "yield:clone-persist-ok";
6053
+ readonly failure: "yield:clone-persist-failed";
6054
+ };
6581
6055
  readonly 'yield:update': {
6582
6056
  readonly result: "yield:update-ok";
6583
6057
  readonly failure: "yield:update-failed";
@@ -7017,7 +6491,7 @@ declare function reconcileSelector(content: string, llm: LlmSelectorInput): Reco
7017
6491
  /**
7018
6492
  * Text encoding utilities for consistent charset handling
7019
6493
  *
7020
- * Ensures frontend decoding matches backend decoding by respecting
6494
+ * Ensures frontend decoding matches gateway decoding by respecting
7021
6495
  * charset parameters in mediaType (e.g., "text/plain; charset=iso-8859-1")
7022
6496
  */
7023
6497
  /**
@@ -7036,7 +6510,7 @@ declare function extractCharset(mediaType: string): string;
7036
6510
  *
7037
6511
  * Uses TextDecoder with the charset extracted from mediaType parameter.
7038
6512
  * This ensures the same character space is used for both annotation creation
7039
- * (backend) and rendering (frontend).
6513
+ * (gateway) and rendering (frontend).
7040
6514
  *
7041
6515
  * @param buffer - Binary data to decode
7042
6516
  * @param mediaType - Media type with optional charset parameter
@@ -7120,11 +6594,16 @@ declare function isValidEmail(email: string): boolean;
7120
6594
  * embedding, never mojibake)
7121
6595
  * - `authorable` — offered in the compose editor's format dropdown
7122
6596
  * - `uploadable` — big tent: true for every registry member
6597
+ * - `generatable` — the generation worker can produce it as a yield artifact
7123
6598
  *
7124
6599
  * Capabilities are orthogonal strategies, not a ladder: images render but
7125
6600
  * yield no text; PDFs yield text but aren't authorable. A "tier" is a
7126
6601
  * derived reading, not a stored fact.
7127
6602
  *
6603
+ * Questions ANSWERABLE from those rows get a helper, never a row of their own —
6604
+ * `isAnnotatable` reads `anchoring`, and a second stored field would be a fact
6605
+ * that can contradict the one it was derived from.
6606
+ *
7128
6607
  * Import-leniency invariant: restore/import preserves archive mediaTypes
7129
6608
  * verbatim, so "every stored mediaType is registry-valid" holds only for
7130
6609
  * content that entered through the validated create/yield gate. No code
@@ -7301,6 +6780,15 @@ declare function baseMediaType(format: string): string;
7301
6780
  declare function isSupportedMediaType(format: string): format is SupportedMediaType;
7302
6781
  /** Capabilities for a format (parameters tolerated), or undefined on registry miss. */
7303
6782
  declare function capabilitiesOf(format: string): MediaTypeCapabilities | undefined;
6783
+ /**
6784
+ * The clone-format gate (MEDIA-TYPES.md Phase 5, moved here for
6785
+ * EXTRACT-ARCHIVIST's clone wire-shape change): a clone opens in the
6786
+ * compose editor, so authorable sources keep their base media type and
6787
+ * everything else falls back to text/plain. Lives beside the registry it
6788
+ * reads; the SDK applies it when deriving a clone upload's format and the
6789
+ * CloneTokenManager's tests pin it.
6790
+ */
6791
+ declare function cloneFormat(sourceMediaType: string | undefined): SupportedMediaType;
7304
6792
  /**
7305
6793
  * Lenient extension lookup for naming foreign/imported content: '.dat' on
7306
6794
  * registry miss. Exporters use this — a vocabulary change must never
@@ -7321,6 +6809,19 @@ declare function mediaTypeForExtension(ext: string): SupportedMediaType | undefi
7321
6809
  * unregistered text subtypes embed too), everything else is 'none'.
7322
6810
  */
7323
6811
  declare function textExtractionOf(format: string): TextExtraction;
6812
+ /**
6813
+ * WHETHER a type can carry annotations — `anchoring` remains the authority on
6814
+ * HOW. Derived rather than stored: a parallel `annotatable` row field would be
6815
+ * two facts that can disagree, with nothing to adjudicate
6816
+ * `{ annotatable: true, anchoring: 'none' }`.
6817
+ *
6818
+ * Strict on a registry miss, where `textExtractionOf` above is lenient. The
6819
+ * asymmetry is deliberate. Extracting the wrong bytes costs one bad vector,
6820
+ * and refusing to extract costs a resource nobody can find, so extraction
6821
+ * guesses; an annotation is a durable write against a coordinate model the
6822
+ * system does not have for an unknown type, so it refuses.
6823
+ */
6824
+ declare function isAnnotatable(format: string): boolean;
7324
6825
  /** Types offered in the compose editor's format dropdown. */
7325
6826
  declare const AUTHORABLE_MEDIA_TYPES: readonly SupportedMediaType[];
7326
6827
  /** Registry rows whose text the Smelter can extract. Rows only — the
@@ -7462,6 +6963,61 @@ interface StateUnit {
7462
6963
  dispose(): void;
7463
6964
  }
7464
6965
 
6966
+ /**
6967
+ * Storage URI Derivation
6968
+ *
6969
+ * Builds the name a resource's content lives under in the working tree, from
6970
+ * its title and validated media type. Extensions come from the media-type
6971
+ * registry; formats are validated upstream at the create/yield boundary, so
6972
+ * the lookup is strict — no fallback.
6973
+ *
6974
+ * Lives in `@semiont/core` rather than `@semiont/content` (moved
6975
+ * 2026-08-24, GENERATION-OUTPUT-FORMAT D10) because the generation form
6976
+ * proposes a default path and react-ui cannot depend on the node-flavoured
6977
+ * content package. This module imports only the registry, so it is
6978
+ * browser-safe.
6979
+ */
6980
+
6981
+ /**
6982
+ * The FILENAME a resource's content takes: slug + the registry's extension.
6983
+ *
6984
+ * The name is lowercased, runs of non-alphanumeric characters collapse to
6985
+ * single hyphens, and leading/trailing hyphens are stripped.
6986
+ *
6987
+ * This is the fragment form, for callers composing a path themselves — the
6988
+ * generation form's input sits beside a `file://` prefix chip, so it must not
6989
+ * strip a prefix this helper just added.
6990
+ *
6991
+ * @example
6992
+ * storageFileName("My Document", "text/markdown") // => "my-document.md"
6993
+ */
6994
+ declare function storageFileName(name: string, format: SupportedMediaType): string;
6995
+ /**
6996
+ * Derive a full `file://` storage URI from a resource name and media type.
6997
+ *
6998
+ * @example
6999
+ * deriveStorageUri("My Document", "text/markdown") // => "file://my-document.md"
7000
+ */
7001
+ declare function deriveStorageUri(name: string, format: SupportedMediaType): string;
7002
+ /**
7003
+ * The folder a resource lives in, WITHOUT a trailing slash — `''` when it sits
7004
+ * at the tree root. Accepts a `file://` URI or a bare path.
7005
+ */
7006
+ declare function folderOf(storageUri: string | undefined): string;
7007
+ /**
7008
+ * The Save location a form PROPOSES: beside the source resource, named for the
7009
+ * title, extended for the chosen format (GENERATION-OUTPUT-FORMAT D11).
7010
+ *
7011
+ * Deriving the whole filename — extension included — has a happy consequence:
7012
+ * while untouched, switching format rewrites the extension too, so D7's
7013
+ * mismatch refusal becomes unreachable except on hand-edited paths. It guards
7014
+ * deliberate edits rather than trapping ordinary use.
7015
+ *
7016
+ * Returns `''` for an empty title: a bare extension (".md") reads as a hidden
7017
+ * file and is nobody's intent.
7018
+ */
7019
+ declare function proposeStoragePath(folder: string, title: string, format: SupportedMediaType): string;
7020
+
7465
7021
  /**
7466
7022
  * Common type guard utilities
7467
7023
  */
@@ -7761,9 +7317,9 @@ interface BuildRequirements {
7761
7317
  }
7762
7318
  /**
7763
7319
  * This interface was referenced by `HttpsSemiontOrgSchemasConfigJson`'s JSON-Schema
7764
- * via the `definition` "BackendServiceConfig".
7320
+ * via the `definition` "GatewayServiceConfig".
7765
7321
  */
7766
- interface BackendServiceConfig {
7322
+ interface GatewayServiceConfig {
7767
7323
  platform: ServicePlatformConfig;
7768
7324
  devMode?: boolean;
7769
7325
  command?: string;
@@ -7812,58 +7368,6 @@ interface BackendServiceConfig {
7812
7368
  [k: string]: string;
7813
7369
  };
7814
7370
  }
7815
- /**
7816
- * This interface was referenced by `HttpsSemiontOrgSchemasConfigJson`'s JSON-Schema
7817
- * via the `definition` "FrontendServiceConfig".
7818
- */
7819
- interface FrontendServiceConfig {
7820
- platform: ServicePlatformConfig;
7821
- devMode?: boolean;
7822
- command?: string;
7823
- port: number;
7824
- siteName: string;
7825
- image?: string;
7826
- projectRoot?: string;
7827
- databaseUrl?: string;
7828
- timeout?: number;
7829
- wait?: number;
7830
- logsEndpoint?: string;
7831
- tag?: string;
7832
- resources?: ResourceRequirements;
7833
- security?: SecurityRequirements;
7834
- build?: boolean | BuildRequirements;
7835
- dockerfile?: string;
7836
- buildContext?: string;
7837
- buildArgs?: {
7838
- [k: string]: string;
7839
- };
7840
- buildTarget?: string;
7841
- prebuilt?: boolean;
7842
- noCache?: boolean;
7843
- secrets?: string[];
7844
- labels?: {
7845
- [k: string]: string;
7846
- };
7847
- annotations?: {
7848
- [k: string]: string;
7849
- };
7850
- dependencies?: string[];
7851
- externalDependencies?: (string | {
7852
- name?: string;
7853
- url?: string;
7854
- required?: boolean;
7855
- healthCheck?: string;
7856
- [k: string]: unknown;
7857
- })[];
7858
- environment?: {
7859
- [k: string]: string;
7860
- };
7861
- env?: {
7862
- [k: string]: string;
7863
- };
7864
- publicURL?: string;
7865
- allowedOrigins?: string[];
7866
- }
7867
7371
  /**
7868
7372
  * This interface was referenced by `HttpsSemiontOrgSchemasConfigJson`'s JSON-Schema
7869
7373
  * via the `definition` "VectorsServiceConfig".
@@ -8034,13 +7538,26 @@ interface McpServiceConfig {
8034
7538
  * via the `definition` "ServicesConfig".
8035
7539
  */
8036
7540
  interface ServicesConfig {
8037
- backend?: BackendServiceConfig;
8038
- frontend?: FrontendServiceConfig;
7541
+ gateway?: GatewayServiceConfig;
8039
7542
  database?: DatabaseServiceConfig;
8040
7543
  graph?: GraphServiceConfig;
8041
7544
  mcp?: McpServiceConfig;
8042
7545
  vectors: VectorsServiceConfig;
8043
7546
  embedding: EmbeddingServiceConfig;
7547
+ archivist?: ArchivistServiceConfig;
7548
+ [k: string]: unknown;
7549
+ }
7550
+ /**
7551
+ * The Archivist service — the out-of-process keeper of the record (EXTRACT-ARCHIVIST). Internal-only: the gateway dials host:port for the D1 sequence-ranged event read path; nothing public.
7552
+ *
7553
+ * This interface was referenced by `HttpsSemiontOrgSchemasConfigJson`'s JSON-Schema
7554
+ * via the `definition` "ArchivistServiceConfig".
7555
+ */
7556
+ interface ArchivistServiceConfig {
7557
+ platform?: ServicePlatformConfig;
7558
+ host?: string;
7559
+ port?: number;
7560
+ image?: string;
8044
7561
  [k: string]: unknown;
8045
7562
  }
8046
7563
  /**
@@ -8055,7 +7572,7 @@ interface SiteConfig {
8055
7572
  /**
8056
7573
  * Primary domain for the site
8057
7574
  */
8058
- domain: string;
7575
+ domain?: string;
8059
7576
  /**
8060
7577
  * Administrator email address
8061
7578
  */
@@ -8130,6 +7647,17 @@ interface EnvironmentConfig {
8130
7647
  * Environment name
8131
7648
  */
8132
7649
  name?: string;
7650
+ /**
7651
+ * The KB's committed identity, staged by the launcher (SINGLE-KB-MOUNT D4). Top-level in the staged file, out of any environment section's reach; never overridable.
7652
+ */
7653
+ kb?: {
7654
+ name: string;
7655
+ domain?: string;
7656
+ /**
7657
+ * Sign-in policy committed in the KB's .semiont/config, staged alongside the identity because the gateway no longer mounts the tree that holds it.
7658
+ */
7659
+ oauthAllowedDomains?: string[];
7660
+ };
8133
7661
  platform?: {
8134
7662
  default?: PlatformType$1;
8135
7663
  [k: string]: unknown;
@@ -8356,8 +7884,8 @@ declare function deriveViews(graph: KnowledgeGraph, mainResourceId: string, foca
8356
7884
  *
8357
7885
  * Exists for startup-critical network calls in long-running peers (worker,
8358
7886
  * smelter, weaver): each authenticates against the KS the moment its
8359
- * container starts, and the backend may not be reachable for a few seconds
8360
- * (backend restart, container-network warm-up). Orchestration runs these
7887
+ * container starts, and the gateway may not be reachable for a few seconds
7888
+ * (gateway restart, container-network warm-up). Orchestration runs these
8361
7889
  * processes with `--rm` and no restart policy, so a process that dies on
8362
7890
  * the first `TypeError: fetch failed` is dead for good — the retry window
8363
7891
  * here is the only recovery it gets.
@@ -8380,7 +7908,7 @@ interface RetryAttemptInfo {
8380
7908
  error: unknown;
8381
7909
  }
8382
7910
  /**
8383
- * Default policy for startup connections to the backend: 8 attempts with
7911
+ * Default policy for startup connections to the gateway: 8 attempts with
8384
7912
  * delays 1s, 2s, 4s, then capped at 8s — ~39s of patience before giving up.
8385
7913
  */
8386
7914
  declare const STARTUP_FETCH_RETRY: RetryPolicy;
@@ -8388,7 +7916,7 @@ declare const STARTUP_FETCH_RETRY: RetryPolicy;
8388
7916
  * True for the errors `fetch` throws when the connection itself fails —
8389
7917
  * undici's `TypeError: fetch failed` (ECONNREFUSED, ENOTFOUND, reset,
8390
7918
  * timeout — the socket error rides in `cause`). Deliberately false for
8391
- * HTTP-level failures (a 401 means the backend is UP and rejected us;
7919
+ * HTTP-level failures (a 401 means the gateway is UP and rejected us;
8392
7920
  * retrying won't change its mind) and for programming errors.
8393
7921
  */
8394
7922
  declare function isTransientFetchError(error: unknown): boolean;
@@ -8466,5 +7994,5 @@ declare function getShardPath(key: string, numBuckets?: number): [string, string
8466
7994
  */
8467
7995
  declare const DISCOVERY_URL_PATH = "/discovery/kbs.json";
8468
7996
 
8469
- export { AUTHORABLE_MEDIA_TYPES, BRIDGED_CHANNELS, BUS_OPERATIONS, BusRequestError, CHANNEL_SCHEMAS, CONTEXT_FULL_WEIGHT, CONTEXT_PARTIAL_WEIGHT, ConfigurationError, ConflictError, DEFAULT_CHUNKING_CONFIG, DISCOVERY_URL_PATH, EMBEDDABLE_MEDIA_TYPES, EventBus, GENERATABLE_MEDIA_TYPES, JWTTokenSchema, LOCALES, MEDIA_TYPES, NotFoundError, PERSISTED_EVENT_TYPES, POSITION_WEIGHT_MAX, POSITION_WINDOW, RESOURCE_BROADCAST_TYPES, STARTUP_FETCH_RETRY, ScopedEventBus, ScriptError, SemiontError, UnauthorizedError, ValidationError, accessToken, agentToDid, anchorAnnotation, anchorRuns, annotationId, annotationUri, applyBodyOperations, assembleAnnotation, authCode, baseMediaType, baseUrl, buildContentCache, burstBuffer, busLog, busLogEnabled, busRequest, capabilitiesOf, chunkText, cloneToken, createCircleSvg, createFragmentSelector, createPolygonSvg, createRectangleSvg, createTomlConfigLoader, decodeRepresentation, decodeWithCharset, deriveViews, didToAgent, email, entityType, errField, estimateTokens, extensionForMediaType, extractBoundingBox, extractCharset, extractContext, findBestTextMatch, findBodyItem, findClaimSpan, formatLocaleDisplay, generateUuid, getAllLocaleCodes, getAllPlatformTypes, getAnnotationExactText, getAnnotationUriFromEvent, getBodySource, getBodyType, getChecksum, getCommentText, getCreator, getDerivedFrom, getExactText, getFragmentSelector, getLanguage, getLocaleEnglishName, getLocaleInfo, getLocaleNativeName, getNodeEncoding, getPageFromFragment, getPrimaryMediaType, getPrimaryRepresentation, getPrimarySelector, getResourceEntityTypes, getResourceId, getShardPath, getStorageUri, getSvgSelector, getTargetSelector, getTargetSource, getTextPositionSelector, getTextQuoteSelector, googleCredential, hasTargetSelector, isAnnotationId, isArchived, isArray, isAssessment, isBodyResolved, isBoolean, isComment, isDefined, isDraft, isEventRelatedToAnnotation, isFunction, isGatheredContext, isGenerationJobParams, isHighlight, isNull, isNullish, isNumber, isObject, isReference, isResolvedReference, isResourceId, isStoredEvent, isString, isStubReference, isSupportedMediaType, isTag, isTextRun, isTransientFetchError, isUndefined, isValidEmail, isValidPlatformType, jobId, jumpConsistentHash, kbDid, loadTomlConfig, locate, mcpToken, mediaTypeForExtension, normalizeCoordinates, normalizeText, parseEnvironment, parseFragmentSelector, parseSvgSelector, reconcileSelector, refreshToken, resourceAnnotationUri, resourceId, resourceUri, retryWithBackoff, scaleSvgToNative, searchQuery, serializePerKey, setBusLogTraceIdProvider, softwareToAgent, textExtractionOf, textUnder, userDID, userId, userToAgent, userToDid, uuidV4, validateData, validateEnvironment, validateSvgMarkup, verifyPosition };
8470
- export type { AccessToken, AnchorConfidence, AnchorMethod, AnchorRect, AnchorSelectors, AnchorStrategy, AnchoredText, AnchoringModel, Annotation, AnnotationCategory, AnnotationId, AnnotationUri, AnthropicProviderConfig, AppConfig, AssembledAnnotation, AuthCode, BackendDownload, BackendServiceConfig, BaseUrl, BodyItem, BodyItemIdentity, BodyOperation, BoundingBox, Brand, BridgedChannel, BurstBufferOptions, BusOp, BusOperationKey, BusOperationSpec, BusRequestErrorCode, BusRequestPrimitive, ChunkingConfig, CloneToken, CollaboratorEntry, ConnectionState, ContentCache, ContentFormat, CreateAnnotationInternal, DatabaseServiceConfig, DiscoveredKB, DiscoveryDocument, Email, EmbeddingServiceConfig, EmittableChannel, EntityType, EntityTypeStats, Environment, EnvironmentConfig, EventBase, EventInput, EventMap, EventMetadata, EventName, EventOfType, EventQuery, EventSignature, ExtractionOutcome, FragmentSelector, FrontendServiceConfig, GatheredContext, GenerationJobParams, GoogleAuthRequest, GoogleCredential, GraphConnection, GraphDatabaseType, GraphPath, GraphServiceConfig, GraphViews, HealthCheckResponse, IBackendOperations, IContentTransport, ITransport, InferenceProvidersConfig, JobId, JobType, ListUsersResponse, LlmSelectorInput, LocaleInfo, Logger, MCPToken, MatchQuality, McpServiceConfig, MediaTypeCapabilities, Motivation, OllamaProviderConfig, PdfCoordinate, PdfTextItem, PdfTextRun, PersistedEvent, PersistedEventType, PlatformType, Point, ProgressCallback, ProgressEvent, PutBinaryOptions, PutBinaryProgress, PutBinaryRequest, ReconciledSelector, RefreshToken, RenderMode, RenderedAnchor, ResourceAnnotationUri, ResourceAnnotations, ResourceBroadcastType, ResourceDescriptor, ResourceFilter, ResourceId, ResourceUri, RetryAttemptInfo, RetryPolicy, SearchQuery, SelectionData, Selector, SemiontConfig, ServicePlatformConfig, ServicesConfig, SiteConfig, StateUnit, StatusResponse, StoredEvent, StoredEventLike, SupportedMediaType, SvgSelector, TagCategory, TagSchema, TextExtraction, TextPosition, TextPositionSelector, TextQuoteSelector, ActorInferenceConfig as TomlActorInferenceConfig, TomlFileReader, InferenceConfig as TomlInferenceConfig, WorkerInferenceConfig as TomlWorkerInferenceConfig, TransportErrorCode, UpdateResourceInput, UpdateUserRequest, UpdateUserResponse, UserDID, UserId, UserResponse, ValidationFailure, ValidationResult, ValidationSuccess, VectorsServiceConfig, components, operations, paths };
7997
+ export { AUTHORABLE_MEDIA_TYPES, BRIDGED_CHANNELS, BUS_OPERATIONS, BusRequestError, CHANNEL_SCHEMAS, CONTEXT_FULL_WEIGHT, CONTEXT_PARTIAL_WEIGHT, ConfigurationError, ConflictError, DEFAULT_CHUNKING_CONFIG, DISCOVERY_URL_PATH, EMBEDDABLE_MEDIA_TYPES, EventBus, GENERATABLE_MEDIA_TYPES, JWTTokenSchema, LOCALES, MEDIA_TYPES, NotFoundError, PERSISTED_EVENT_TYPES, POSITION_WEIGHT_MAX, POSITION_WINDOW, RESOURCE_BROADCAST_TYPES, STARTUP_FETCH_RETRY, ScopedEventBus, ScriptError, SemiontError, UnauthorizedError, ValidationError, accessToken, agentToDid, anchorAnnotation, anchorRuns, annotationId, annotationUri, applyBodyOperations, assembleAnnotation, authCode, baseMediaType, baseUrl, buildContentCache, burstBuffer, busLog, busLogEnabled, busRequest, capabilitiesOf, chunkText, cloneFormat, cloneToken, createCircleSvg, createFragmentSelector, createPolygonSvg, createRectangleSvg, createTomlConfigLoader, decodeRepresentation, decodeWithCharset, deriveStorageUri, deriveViews, didToAgent, email, entityType, errField, estimateTokens, extensionForMediaType, extractBoundingBox, extractCharset, extractContext, findBestTextMatch, findBodyItem, findClaimSpan, folderOf, formatLocaleDisplay, generateUuid, getAllLocaleCodes, getAllPlatformTypes, getAnnotationExactText, getAnnotationUriFromEvent, getBodySource, getBodyType, getChecksum, getCommentText, getCreator, getDerivedFrom, getExactText, getFragmentSelector, getLanguage, getLocaleEnglishName, getLocaleInfo, getLocaleNativeName, getNodeEncoding, getPageFromFragment, getPrimaryMediaType, getPrimaryRepresentation, getPrimarySelector, getResourceEntityTypes, getResourceId, getShardPath, getStorageUri, getSvgSelector, getTargetSelector, getTargetSource, getTextPositionSelector, getTextQuoteSelector, googleCredential, hasTargetSelector, isAnnotatable, isAnnotationId, isArchived, isArray, isAssessment, isBodyResolved, isBoolean, isComment, isDefined, isDraft, isEventRelatedToAnnotation, isFunction, isGatheredContext, isGenerationJobParams, isHighlight, isNull, isNullish, isNumber, isObject, isReference, isResolvedReference, isResourceId, isStoredEvent, isString, isStubReference, isSupportedMediaType, isTag, isTextRun, isTransientFetchError, isUndefined, isValidEmail, isValidPlatformType, jobId, jumpConsistentHash, kbDid, loadTomlConfig, locate, mcpToken, mediaTypeForExtension, normalizeCoordinates, normalizeText, parseEnvironment, parseFragmentSelector, parseSvgSelector, proposeStoragePath, reconcileSelector, refreshToken, resourceAnnotationUri, resourceId, resourceUri, retryWithBackoff, scaleSvgToNative, searchQuery, serializePerKey, setBusLogTraceIdProvider, softwareToAgent, storageFileName, textExtractionOf, textUnder, userDID, userId, userToAgent, userToDid, uuidV4, validateData, validateEnvironment, validateSvgMarkup, verifyPosition };
7998
+ export type { AccessToken, AnchorConfidence, AnchorMethod, AnchorRect, AnchorSelectors, AnchorStrategy, AnchoredText, AnchoringModel, Annotation, AnnotationCategory, AnnotationId, AnnotationUri, AnthropicProviderConfig, AppConfig, ArchivistServiceConfig, AssembledAnnotation, AuthCode, BaseUrl, BodyItem, BodyItemIdentity, BodyOperation, BoundingBox, Brand, BridgedChannel, BurstBufferOptions, BusOp, BusOperationKey, BusOperationSpec, BusRequestErrorCode, BusRequestPrimitive, ChunkingConfig, CloneToken, CollaboratorEntry, ConnectionState, ContentCache, ContentFormat, CreateAnnotationInternal, DatabaseServiceConfig, DiscoveredKB, DiscoveryDocument, Email, EmbeddingServiceConfig, EmittableChannel, EntityType, EntityTypeStats, Environment, EnvironmentConfig, EventBase, EventInput, EventMap, EventMetadata, EventName, EventOfType, EventQuery, EventSignature, ExtractionOutcome, FragmentSelector, GatewayServiceConfig, GatheredContext, GenerationJobParams, GoogleAuthRequest, GoogleCredential, GraphConnection, GraphDatabaseType, GraphPath, GraphServiceConfig, GraphViews, HealthCheckResponse, IContentTransport, IGatewayOperations, ITransport, InferenceProvidersConfig, JobId, JobType, ListUsersResponse, LlmSelectorInput, LocaleInfo, Logger, MCPToken, MatchQuality, McpServiceConfig, MediaTypeCapabilities, Motivation, OllamaProviderConfig, PdfCoordinate, PdfTextItem, PdfTextRun, PersistedEvent, PersistedEventType, PlatformType, Point, PutBinaryOptions, PutBinaryProgress, PutBinaryRequest, ReconciledSelector, RefreshToken, RenderMode, RenderedAnchor, ResourceAnnotationUri, ResourceAnnotations, ResourceBroadcastType, ResourceDescriptor, ResourceFilter, ResourceId, ResourceUri, RetryAttemptInfo, RetryPolicy, SearchQuery, SelectionData, Selector, SemiontConfig, ServicePlatformConfig, ServicesConfig, SiteConfig, StateUnit, StatusResponse, StoredEvent, StoredEventLike, SupportedMediaType, SvgSelector, TagCategory, TagSchema, TextExtraction, TextPosition, TextPositionSelector, TextQuoteSelector, ActorInferenceConfig as TomlActorInferenceConfig, TomlFileReader, InferenceConfig as TomlInferenceConfig, WorkerInferenceConfig as TomlWorkerInferenceConfig, TransportErrorCode, UpdateResourceInput, UpdateUserRequest, UpdateUserResponse, UserDID, UserId, UserResponse, ValidationFailure, ValidationResult, ValidationSuccess, VectorsServiceConfig, components, operations, paths };