@mossbear/protocol 0.1.0-alpha.83 → 0.1.0-alpha.84

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/schemas.d.ts CHANGED
@@ -1045,7 +1045,7 @@ export type FindingTier = v.InferOutput<typeof FindingTierSchema>;
1045
1045
  * model-authored and arrives inside them. A finding never carries replacement
1046
1046
  * text: the reader's agent has the repository and writes the fix.
1047
1047
  */
1048
- export declare const ContextItemFindingSchema: v.ObjectSchema<{
1048
+ export declare const CommentFindingSchema: v.ObjectSchema<{
1049
1049
  readonly tier: v.PicklistSchema<["observed", "usage", "practice"], undefined>;
1050
1050
  /** How the finding is known, in one line: "Seen in 3 sessions (2026-09-15 – 2026-10-03)". */
1051
1051
  readonly tierLine: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 300, undefined>]>;
@@ -1054,7 +1054,7 @@ export declare const ContextItemFindingSchema: v.ObjectSchema<{
1054
1054
  /** What should change in later sessions if the finding is fixed, wrapped in the untrusted markers. */
1055
1055
  readonly prediction: v.NullableSchema<v.StringSchema<undefined>, undefined>;
1056
1056
  }, undefined>;
1057
- export type ContextItemFinding = v.InferOutput<typeof ContextItemFindingSchema>;
1057
+ export type CommentFinding = v.InferOutput<typeof CommentFindingSchema>;
1058
1058
  /**
1059
1059
  * One comment a **person** left about a context item, riding the item it is about.
1060
1060
  *
@@ -1068,6 +1068,92 @@ export type ContextItemFinding = v.InferOutput<typeof ContextItemFindingSchema>;
1068
1068
  * received them and never re-wraps them: the markers are derived against the
1069
1069
  * bodies the server sent, so a second wrapping cannot claim the same guarantee.
1070
1070
  */
1071
+ export declare const ArtifactCommentSchema: v.ObjectSchema<{
1072
+ readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
1073
+ readonly state: v.OptionalSchema<v.PicklistSchema<["open", "resolved"], undefined>, undefined>;
1074
+ /** Current source location of an anchored passage, or its lost quote. */
1075
+ readonly passage: v.OptionalSchema<v.ObjectSchema<{
1076
+ readonly quote: v.StringSchema<undefined>;
1077
+ readonly status: v.PicklistSchema<["located", "changed", "orphaned"], undefined>;
1078
+ readonly lines: v.NullableSchema<v.ObjectSchema<{
1079
+ readonly start: v.NumberSchema<undefined>;
1080
+ readonly end: v.NumberSchema<undefined>;
1081
+ }, undefined>, undefined>;
1082
+ }, undefined>, undefined>;
1083
+ /** The comment's text, already wrapped in the response's untrusted markers. */
1084
+ readonly body: v.StringSchema<undefined>;
1085
+ /**
1086
+ * A suggested edit: the replacement for the passage at `passage.lines`,
1087
+ * already wrapped in the response's untrusted markers like `body`. An
1088
+ * insertion is the passage plus its new lines and an empty replacement is a
1089
+ * deletion, so every edit is one replace. Absent on an ordinary comment.
1090
+ */
1091
+ readonly suggestion: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
1092
+ /**
1093
+ * What a comment Mossbear wrote is: a finding about the item, never an edit.
1094
+ * Present only on a Mossbear comment. The comment's `body` begins with the
1095
+ * claim (what goes wrong); this carries what the claim rests on.
1096
+ */
1097
+ readonly finding: v.OptionalSchema<v.ObjectSchema<{
1098
+ readonly tier: v.PicklistSchema<["observed", "usage", "practice"], undefined>;
1099
+ /** How the finding is known, in one line: "Seen in 3 sessions (2026-09-15 – 2026-10-03)". */
1100
+ readonly tierLine: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 300, undefined>]>;
1101
+ /** What the drafter did not read, fixed per tier. */
1102
+ readonly blindSpot: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 300, undefined>]>;
1103
+ /** What should change in later sessions if the finding is fixed, wrapped in the untrusted markers. */
1104
+ readonly prediction: v.NullableSchema<v.StringSchema<undefined>, undefined>;
1105
+ }, undefined>, undefined>;
1106
+ /**
1107
+ * Whether the person approved a comment Mossbear drafted. Present on every
1108
+ * Mossbear comment and absent on a person's or an agent's, which are
1109
+ * requests as written. `false` is a draft nobody has read yet: a reader shows
1110
+ * it to the user and acts only on their go-ahead. Only a client that reports
1111
+ * a version able to mark drafts is ever listed one, so an older reader that
1112
+ * strips this field never receives a draft it would print as a request.
1113
+ */
1114
+ readonly approved: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
1115
+ /** The author's display name as the workspace shows it, or null. Never an email. */
1116
+ readonly authorName: v.NullableSchema<v.StringSchema<undefined>, undefined>;
1117
+ /** ISO timestamp, machine format. */
1118
+ readonly createdAt: v.StringSchema<undefined>;
1119
+ /** The item's content version the comment was written against. */
1120
+ readonly itemVersion: v.NumberSchema<undefined>;
1121
+ /** True when the item's current version is greater than `itemVersion`. */
1122
+ readonly itemChangedSince: v.BooleanSchema<undefined>;
1123
+ /**
1124
+ * How many agent reads were handed this comment **before** this one — so a
1125
+ * comment reaching an agent for the first time reports `0`.
1126
+ *
1127
+ * It is the stored count as it read at the moment the response was built;
1128
+ * the serve this response *is* has not been counted yet. Excluded rather
1129
+ * than included because the count is recorded best-effort: a response that
1130
+ * claimed to include itself would be wrong whenever that record failed, and
1131
+ * a number that is sometimes off by one is worse than one that is
1132
+ * consistently the prior total.
1133
+ *
1134
+ * So `deliveredCount > 0` means an earlier read was handed this comment, and
1135
+ * `0` means this read is the first. Neither says a model took it in — only
1136
+ * that the server handed it over.
1137
+ */
1138
+ readonly deliveredCount: v.NumberSchema<undefined>;
1139
+ /**
1140
+ * This comment's thread root — its own id for every delivered root. Resolution
1141
+ * replies remain on the dashboard thread and are not delivered to agents.
1142
+ * It is on the wire from the first response
1143
+ * because the wire contract is consumed by installed CLI versions: reshaping
1144
+ * a flat `comments` array into threads-of-comments later would be a breaking
1145
+ * change, while a field today's readers ignore costs them nothing.
1146
+ */
1147
+ readonly threadId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
1148
+ /**
1149
+ * Always `null` for a delivered root. Present so an older reader meeting a
1150
+ * future response that carries real replies degrades to
1151
+ * "a flat list of comments" rather than failing to parse.
1152
+ */
1153
+ readonly replyToId: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, undefined>;
1154
+ }, undefined>;
1155
+ export type ArtifactComment = v.InferOutput<typeof ArtifactCommentSchema>;
1156
+ /** The item routes' name for `ArtifactCommentSchema`, kept while those routes are served. */
1071
1157
  export declare const ContextItemCommentSchema: v.ObjectSchema<{
1072
1158
  readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
1073
1159
  readonly state: v.OptionalSchema<v.PicklistSchema<["open", "resolved"], undefined>, undefined>;
@@ -1152,7 +1238,7 @@ export declare const ContextItemCommentSchema: v.ObjectSchema<{
1152
1238
  */
1153
1239
  readonly replyToId: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, undefined>;
1154
1240
  }, undefined>;
1155
- export type ContextItemComment = v.InferOutput<typeof ContextItemCommentSchema>;
1241
+ export type ContextItemComment = ArtifactComment;
1156
1242
  /**
1157
1243
  * The revision published bytes were read from — 40 hex characters for a sha1
1158
1244
  * repository, 64 for a sha256 one. Lowercase only, because that is what
@@ -1199,15 +1285,26 @@ export declare const GitSourceSchema: v.ObjectSchema<{
1199
1285
  */
1200
1286
  readonly branch: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 255, undefined>]>, undefined>;
1201
1287
  }, undefined>;
1202
- export declare const ContextItemSchema: v.ObjectSchema<{
1288
+ /**
1289
+ * A bundle read's item. `type` is filled in from the rest of the item when the
1290
+ * server no longer sends it (`contextItemTypeOf`), so every reader keeps one
1291
+ * answer to "is this a guide" whichever server it is talking to.
1292
+ */
1293
+ export declare const ContextItemSchema: v.SchemaWithPipe<readonly [v.ObjectSchema<{
1203
1294
  readonly id: v.StringSchema<undefined>;
1204
1295
  /**
1205
1296
  * The id every artifact route addresses: the body file's id for a guide
1206
1297
  * (null only for a guide with no body yet), the item's own id otherwise.
1207
- * Optional so a client tolerates a server that predates it.
1298
+ * Optional so a client tolerates a server that predates it, and one that
1299
+ * stops sending it (the item id is the artifact id).
1208
1300
  */
1209
1301
  readonly artifactId: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
1210
- readonly type: v.PicklistSchema<string[], undefined>;
1302
+ /**
1303
+ * Leaving the wire: a reader tells a guide from content by `role` and the
1304
+ * guide fields, not by this. Optional so a client parses a server that no
1305
+ * longer sends it.
1306
+ */
1307
+ readonly type: v.OptionalSchema<v.PicklistSchema<string[], undefined>, undefined>;
1211
1308
  readonly name: v.StringSchema<undefined>;
1212
1309
  /**
1213
1310
  * The stored `(role, format)` pair, as two bare nullable strings.
@@ -1459,17 +1556,131 @@ export declare const ContextItemSchema: v.ObjectSchema<{
1459
1556
  * than a tombstone that says no.
1460
1557
  */
1461
1558
  readonly removed: v.OptionalSchema<v.LiteralSchema<true, undefined>, undefined>;
1462
- }, undefined>;
1559
+ }, undefined>, v.TransformAction<{
1560
+ id: string;
1561
+ artifactId?: string | null | undefined;
1562
+ type?: string | undefined;
1563
+ name: string;
1564
+ role: string | null;
1565
+ format: string | null;
1566
+ content: string | null;
1567
+ origin?: string | null | undefined;
1568
+ version?: number | undefined;
1569
+ guideId?: string | null | undefined;
1570
+ root?: "project" | "global" | null | undefined;
1571
+ path?: string | null | undefined;
1572
+ projectId?: string | null | undefined;
1573
+ pathProjectId?: string | null | undefined;
1574
+ aliases?: {
1575
+ root: "project" | "global";
1576
+ path: string;
1577
+ }[] | undefined;
1578
+ comments?: {
1579
+ id: string;
1580
+ state?: "open" | "resolved" | undefined;
1581
+ passage?: {
1582
+ quote: string;
1583
+ status: "located" | "changed" | "orphaned";
1584
+ lines: {
1585
+ start: number;
1586
+ end: number;
1587
+ } | null;
1588
+ } | undefined;
1589
+ body: string;
1590
+ suggestion?: string | undefined;
1591
+ finding?: {
1592
+ tier: "observed" | "usage" | "practice";
1593
+ tierLine: string;
1594
+ blindSpot: string;
1595
+ prediction: string | null;
1596
+ } | undefined;
1597
+ approved?: boolean | undefined;
1598
+ authorName: string | null;
1599
+ createdAt: string;
1600
+ itemVersion: number;
1601
+ itemChangedSince: boolean;
1602
+ deliveredCount: number;
1603
+ threadId: string;
1604
+ replyToId: string | null;
1605
+ }[] | undefined;
1606
+ updatedAt: string;
1607
+ gitSource?: {
1608
+ projectId: string;
1609
+ commitSha: string;
1610
+ branch?: string | undefined;
1611
+ } | null | undefined;
1612
+ removed?: true | undefined;
1613
+ }, {
1614
+ type: string;
1615
+ id: string;
1616
+ artifactId?: string | null | undefined;
1617
+ name: string;
1618
+ role: string | null;
1619
+ format: string | null;
1620
+ content: string | null;
1621
+ origin?: string | null | undefined;
1622
+ version?: number | undefined;
1623
+ guideId?: string | null | undefined;
1624
+ root?: "project" | "global" | null | undefined;
1625
+ path?: string | null | undefined;
1626
+ projectId?: string | null | undefined;
1627
+ pathProjectId?: string | null | undefined;
1628
+ aliases?: {
1629
+ root: "project" | "global";
1630
+ path: string;
1631
+ }[] | undefined;
1632
+ comments?: {
1633
+ id: string;
1634
+ state?: "open" | "resolved" | undefined;
1635
+ passage?: {
1636
+ quote: string;
1637
+ status: "located" | "changed" | "orphaned";
1638
+ lines: {
1639
+ start: number;
1640
+ end: number;
1641
+ } | null;
1642
+ } | undefined;
1643
+ body: string;
1644
+ suggestion?: string | undefined;
1645
+ finding?: {
1646
+ tier: "observed" | "usage" | "practice";
1647
+ tierLine: string;
1648
+ blindSpot: string;
1649
+ prediction: string | null;
1650
+ } | undefined;
1651
+ approved?: boolean | undefined;
1652
+ authorName: string | null;
1653
+ createdAt: string;
1654
+ itemVersion: number;
1655
+ itemChangedSince: boolean;
1656
+ deliveredCount: number;
1657
+ threadId: string;
1658
+ replyToId: string | null;
1659
+ }[] | undefined;
1660
+ updatedAt: string;
1661
+ gitSource?: {
1662
+ projectId: string;
1663
+ commitSha: string;
1664
+ branch?: string | undefined;
1665
+ } | null | undefined;
1666
+ removed?: true | undefined;
1667
+ }>]>;
1463
1668
  export declare const ContextItemsResponseSchema: v.ObjectSchema<{
1464
- readonly items: v.ArraySchema<v.ObjectSchema<{
1669
+ readonly items: v.ArraySchema<v.SchemaWithPipe<readonly [v.ObjectSchema<{
1465
1670
  readonly id: v.StringSchema<undefined>;
1466
1671
  /**
1467
1672
  * The id every artifact route addresses: the body file's id for a guide
1468
1673
  * (null only for a guide with no body yet), the item's own id otherwise.
1469
- * Optional so a client tolerates a server that predates it.
1674
+ * Optional so a client tolerates a server that predates it, and one that
1675
+ * stops sending it (the item id is the artifact id).
1470
1676
  */
1471
1677
  readonly artifactId: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
1472
- readonly type: v.PicklistSchema<string[], undefined>;
1678
+ /**
1679
+ * Leaving the wire: a reader tells a guide from content by `role` and the
1680
+ * guide fields, not by this. Optional so a client parses a server that no
1681
+ * longer sends it.
1682
+ */
1683
+ readonly type: v.OptionalSchema<v.PicklistSchema<string[], undefined>, undefined>;
1473
1684
  readonly name: v.StringSchema<undefined>;
1474
1685
  /**
1475
1686
  * The stored `(role, format)` pair, as two bare nullable strings.
@@ -1721,63 +1932,171 @@ export declare const ContextItemsResponseSchema: v.ObjectSchema<{
1721
1932
  * than a tombstone that says no.
1722
1933
  */
1723
1934
  readonly removed: v.OptionalSchema<v.LiteralSchema<true, undefined>, undefined>;
1724
- }, undefined>, undefined>;
1725
- /**
1726
- * The markers every comment `body` in this response is wrapped in, plus a
1727
- * statement of what they mean. Present exactly when at least one item
1728
- * carries a comment — there is nothing to delimit otherwise.
1729
- */
1730
- readonly untrusted: v.OptionalSchema<v.NullableSchema<v.ObjectSchema<{
1731
- readonly token: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
1732
- readonly startMarker: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
1733
- readonly endMarker: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
1734
- readonly note: v.StringSchema<undefined>;
1735
- }, undefined>, undefined>, undefined>;
1736
- }, undefined>;
1737
- /**
1738
- * How many bundles one comments read may name.
1739
- *
1740
- * A repo's delivery set is the union of its committed subscriptions and the
1741
- * reader's account ones, so this bounds a request, not a product limit: a
1742
- * reader subscribing to more bundles than this asks in two calls rather than
1743
- * losing the tail silently.
1744
- */
1745
- export declare const MAX_COMMENT_BUNDLE_IDS = 100;
1746
- /**
1747
- * How many times one subscriber is told, in one repo, that a given comment is
1748
- * waiting before the hook falls silent about it.
1749
- *
1750
- * **A cap on the interruption, never on the comment.** After it is reached the
1751
- * comment is still open, still on the item page, and still returned in full by
1752
- * the on-demand read — it simply stops being announced in front of the first
1753
- * turn of every session. So silence here means "nothing new to interrupt you
1754
- * about", never "nobody left anything".
1755
- *
1756
- * Three rather than one, for the reason the announcement exists: the first
1757
- * session in a repo is often doing unrelated work, so a one-shot announcement
1758
- * would routinely spend itself on the session least likely to act. Three is a
1759
- * judgement, named so replacing it is one edit — the same discipline the live
1760
- * session window is held to.
1761
- */
1762
- export declare const MAX_COMMENT_ANNOUNCEMENTS_PER_REPO = 3;
1763
- /**
1764
- * Ask which comments are waiting for this reader in this repo, and be counted as
1765
- * told.
1766
- *
1767
- * **A write, because being told is a fact the server has to keep.** The count
1768
- * cannot be `item_comments.delivered_count` — that is one global number across
1769
- * every subscriber and every repo, so one reader's fill of a comment would
1770
- * silence it for everyone — and it cannot live in the checkout, because the
1771
- * disposable environments this exists for rebuild the clone every session and
1772
- * a counter there resets with it, announcing every unresolved comment as new
1773
- * forever.
1774
- */
1775
- export declare const AnnounceItemCommentsRequestSchema: v.ObjectSchema<{
1776
- /**
1777
- * The repo, as its committed config declares it. Required: it is the scope
1778
- * the count is kept under, and a request with nothing to key on could only
1779
- * be answered by an uncapped announcement — which is the repeating broadcast
1780
- * this route exists to end.
1935
+ }, undefined>, v.TransformAction<{
1936
+ id: string;
1937
+ artifactId?: string | null | undefined;
1938
+ type?: string | undefined;
1939
+ name: string;
1940
+ role: string | null;
1941
+ format: string | null;
1942
+ content: string | null;
1943
+ origin?: string | null | undefined;
1944
+ version?: number | undefined;
1945
+ guideId?: string | null | undefined;
1946
+ root?: "project" | "global" | null | undefined;
1947
+ path?: string | null | undefined;
1948
+ projectId?: string | null | undefined;
1949
+ pathProjectId?: string | null | undefined;
1950
+ aliases?: {
1951
+ root: "project" | "global";
1952
+ path: string;
1953
+ }[] | undefined;
1954
+ comments?: {
1955
+ id: string;
1956
+ state?: "open" | "resolved" | undefined;
1957
+ passage?: {
1958
+ quote: string;
1959
+ status: "located" | "changed" | "orphaned";
1960
+ lines: {
1961
+ start: number;
1962
+ end: number;
1963
+ } | null;
1964
+ } | undefined;
1965
+ body: string;
1966
+ suggestion?: string | undefined;
1967
+ finding?: {
1968
+ tier: "observed" | "usage" | "practice";
1969
+ tierLine: string;
1970
+ blindSpot: string;
1971
+ prediction: string | null;
1972
+ } | undefined;
1973
+ approved?: boolean | undefined;
1974
+ authorName: string | null;
1975
+ createdAt: string;
1976
+ itemVersion: number;
1977
+ itemChangedSince: boolean;
1978
+ deliveredCount: number;
1979
+ threadId: string;
1980
+ replyToId: string | null;
1981
+ }[] | undefined;
1982
+ updatedAt: string;
1983
+ gitSource?: {
1984
+ projectId: string;
1985
+ commitSha: string;
1986
+ branch?: string | undefined;
1987
+ } | null | undefined;
1988
+ removed?: true | undefined;
1989
+ }, {
1990
+ type: string;
1991
+ id: string;
1992
+ artifactId?: string | null | undefined;
1993
+ name: string;
1994
+ role: string | null;
1995
+ format: string | null;
1996
+ content: string | null;
1997
+ origin?: string | null | undefined;
1998
+ version?: number | undefined;
1999
+ guideId?: string | null | undefined;
2000
+ root?: "project" | "global" | null | undefined;
2001
+ path?: string | null | undefined;
2002
+ projectId?: string | null | undefined;
2003
+ pathProjectId?: string | null | undefined;
2004
+ aliases?: {
2005
+ root: "project" | "global";
2006
+ path: string;
2007
+ }[] | undefined;
2008
+ comments?: {
2009
+ id: string;
2010
+ state?: "open" | "resolved" | undefined;
2011
+ passage?: {
2012
+ quote: string;
2013
+ status: "located" | "changed" | "orphaned";
2014
+ lines: {
2015
+ start: number;
2016
+ end: number;
2017
+ } | null;
2018
+ } | undefined;
2019
+ body: string;
2020
+ suggestion?: string | undefined;
2021
+ finding?: {
2022
+ tier: "observed" | "usage" | "practice";
2023
+ tierLine: string;
2024
+ blindSpot: string;
2025
+ prediction: string | null;
2026
+ } | undefined;
2027
+ approved?: boolean | undefined;
2028
+ authorName: string | null;
2029
+ createdAt: string;
2030
+ itemVersion: number;
2031
+ itemChangedSince: boolean;
2032
+ deliveredCount: number;
2033
+ threadId: string;
2034
+ replyToId: string | null;
2035
+ }[] | undefined;
2036
+ updatedAt: string;
2037
+ gitSource?: {
2038
+ projectId: string;
2039
+ commitSha: string;
2040
+ branch?: string | undefined;
2041
+ } | null | undefined;
2042
+ removed?: true | undefined;
2043
+ }>]>, undefined>;
2044
+ /**
2045
+ * The markers every comment `body` in this response is wrapped in, plus a
2046
+ * statement of what they mean. Present exactly when at least one item
2047
+ * carries a comment — there is nothing to delimit otherwise.
2048
+ */
2049
+ readonly untrusted: v.OptionalSchema<v.NullableSchema<v.ObjectSchema<{
2050
+ readonly token: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
2051
+ readonly startMarker: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
2052
+ readonly endMarker: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
2053
+ readonly note: v.StringSchema<undefined>;
2054
+ }, undefined>, undefined>, undefined>;
2055
+ }, undefined>;
2056
+ /**
2057
+ * How many bundles one comments read may name.
2058
+ *
2059
+ * A repo's delivery set is the union of its committed subscriptions and the
2060
+ * reader's account ones, so this bounds a request, not a product limit: a
2061
+ * reader subscribing to more bundles than this asks in two calls rather than
2062
+ * losing the tail silently.
2063
+ */
2064
+ export declare const MAX_COMMENT_BUNDLE_IDS = 100;
2065
+ /**
2066
+ * How many times one subscriber is told, in one repo, that a given comment is
2067
+ * waiting before the hook falls silent about it.
2068
+ *
2069
+ * **A cap on the interruption, never on the comment.** After it is reached the
2070
+ * comment is still open, still on the item page, and still returned in full by
2071
+ * the on-demand read — it simply stops being announced in front of the first
2072
+ * turn of every session. So silence here means "nothing new to interrupt you
2073
+ * about", never "nobody left anything".
2074
+ *
2075
+ * Three rather than one, for the reason the announcement exists: the first
2076
+ * session in a repo is often doing unrelated work, so a one-shot announcement
2077
+ * would routinely spend itself on the session least likely to act. Three is a
2078
+ * judgement, named so replacing it is one edit — the same discipline the live
2079
+ * session window is held to.
2080
+ */
2081
+ export declare const MAX_COMMENT_ANNOUNCEMENTS_PER_REPO = 3;
2082
+ /**
2083
+ * Ask which comments are waiting for this reader in this repo, and be counted as
2084
+ * told.
2085
+ *
2086
+ * **A write, because being told is a fact the server has to keep.** The count
2087
+ * cannot be `item_comments.delivered_count` — that is one global number across
2088
+ * every subscriber and every repo, so one reader's fill of a comment would
2089
+ * silence it for everyone — and it cannot live in the checkout, because the
2090
+ * disposable environments this exists for rebuild the clone every session and
2091
+ * a counter there resets with it, announcing every unresolved comment as new
2092
+ * forever.
2093
+ */
2094
+ export declare const AnnounceItemCommentsRequestSchema: v.ObjectSchema<{
2095
+ /**
2096
+ * The repo, as its committed config declares it. Required: it is the scope
2097
+ * the count is kept under, and a request with nothing to key on could only
2098
+ * be answered by an uncapped announcement — which is the repeating broadcast
2099
+ * this route exists to end.
1781
2100
  */
1782
2101
  readonly projectId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 128, undefined>, v.RegexAction<string, "projectId must contain only letters, digits, underscore, dot or hyphen">]>;
1783
2102
  /**
@@ -1827,9 +2146,10 @@ export type AgentCommentErrorCode = v.InferOutput<typeof AgentCommentErrorCodeSc
1827
2146
  /**
1828
2147
  * Leave a comment, or reply to one, as an agent (`POST /api/v1/context/comments`).
1829
2148
  *
1830
- * **`target` names what the comment is about, one way.** `item` is the id a
1831
- * bundle read gave for a guide or document, `session` is an agent session id of
1832
- * the caller's own (the key a search hit and the session digest hand out), and
2149
+ * **`target` names what the comment is about, one way.** `artifact` is the id
2150
+ * a bundle read gave for a guide or document, and `item` is its older name for
2151
+ * the same thing, accepted until every client sends `artifact`. `session` is an
2152
+ * agent session id of the caller's own (the key a search hit and the session digest hand out), and
1833
2153
  * `reply` is the id of a comment to answer. A reply joins that comment's thread
1834
2154
  * and the subject it is about.
1835
2155
  *
@@ -1845,6 +2165,9 @@ export type AgentCommentErrorCode = v.InferOutput<typeof AgentCommentErrorCodeSc
1845
2165
  */
1846
2166
  export declare const AgentCommentRequestSchema: v.ObjectSchema<{
1847
2167
  readonly target: v.VariantSchema<"kind", [v.ObjectSchema<{
2168
+ readonly kind: v.LiteralSchema<"artifact", undefined>;
2169
+ readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 128, undefined>]>;
2170
+ }, undefined>, v.ObjectSchema<{
1848
2171
  readonly kind: v.LiteralSchema<"item", undefined>;
1849
2172
  readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 128, undefined>]>;
1850
2173
  }, undefined>, v.ObjectSchema<{
@@ -1882,7 +2205,7 @@ export declare const AgentCommentResponseSchema: v.ObjectSchema<{
1882
2205
  readonly id: v.StringSchema<undefined>;
1883
2206
  readonly threadId: v.StringSchema<undefined>;
1884
2207
  readonly subject: v.ObjectSchema<{
1885
- readonly kind: v.PicklistSchema<["item", "session"], undefined>;
2208
+ readonly kind: v.PicklistSchema<["artifact", "item", "session"], undefined>;
1886
2209
  readonly id: v.StringSchema<undefined>;
1887
2210
  }, undefined>;
1888
2211
  readonly body: v.StringSchema<undefined>;
@@ -2366,15 +2689,21 @@ export declare const PushContextRequestSchema: v.ObjectSchema<{
2366
2689
  }, undefined>, undefined>;
2367
2690
  }, undefined>;
2368
2691
  export declare const PushContextResponseSchema: v.ObjectSchema<{
2369
- readonly item: v.ObjectSchema<{
2692
+ readonly item: v.SchemaWithPipe<readonly [v.ObjectSchema<{
2370
2693
  readonly id: v.StringSchema<undefined>;
2371
2694
  /**
2372
2695
  * The id every artifact route addresses: the body file's id for a guide
2373
2696
  * (null only for a guide with no body yet), the item's own id otherwise.
2374
- * Optional so a client tolerates a server that predates it.
2697
+ * Optional so a client tolerates a server that predates it, and one that
2698
+ * stops sending it (the item id is the artifact id).
2375
2699
  */
2376
2700
  readonly artifactId: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
2377
- readonly type: v.PicklistSchema<string[], undefined>;
2701
+ /**
2702
+ * Leaving the wire: a reader tells a guide from content by `role` and the
2703
+ * guide fields, not by this. Optional so a client parses a server that no
2704
+ * longer sends it.
2705
+ */
2706
+ readonly type: v.OptionalSchema<v.PicklistSchema<string[], undefined>, undefined>;
2378
2707
  readonly name: v.StringSchema<undefined>;
2379
2708
  /**
2380
2709
  * The stored `(role, format)` pair, as two bare nullable strings.
@@ -2626,106 +2955,220 @@ export declare const PushContextResponseSchema: v.ObjectSchema<{
2626
2955
  * than a tombstone that says no.
2627
2956
  */
2628
2957
  readonly removed: v.OptionalSchema<v.LiteralSchema<true, undefined>, undefined>;
2629
- }, undefined>;
2630
- readonly created: v.BooleanSchema<undefined>;
2631
- }, undefined>;
2632
- export declare const UpdateContextItemRequestSchema: v.ObjectSchema<{
2633
- readonly itemId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
2634
- readonly name: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 200, undefined>]>, undefined>;
2635
- readonly content: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.CheckAction<string, "content must be at most 524288 bytes">]>, undefined>;
2636
- readonly expectedVersion: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>, undefined>;
2637
- /**
2638
- * The committed `project.id` of the checkout this write comes from — same
2639
- * meaning and same two uses as on `PushContextRequestSchema`: a bundle that
2640
- * claims a home accepts writes only from that repo, and a request declaring
2641
- * nothing is not it; and when this update sets `path`, it is stored as the
2642
- * repo that path is placed in. Parsed as on `PushContextRequestSchema`.
2643
- */
2644
- readonly projectId: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>, undefined>;
2645
- /**
2646
- * Move the document: its new placement, or `null` to take the placement away
2647
- * so it lands in the bundle folder again.
2648
- *
2649
- * **Three states, the same shape `sourceItemIds` takes.** Omitted leaves the
2650
- * stored path and its home alone — every name or body edit. A path replaces
2651
- * both: the path, and the home as `projectId` above declares it, since a path
2652
- * is relative to the repo that declared it. `null` clears both.
2653
- *
2654
- * The same schema as the create side and the read side, for the reason
2655
- * `PushContextRequestSchema` gives, and the same refusals in the routes —
2656
- * agent guidance, Mossbear's state directory, git's.
2657
- *
2658
- * **Documents only.** A guide's path is its discovery path, which import
2659
- * reconciles on; moving it here would fork it from the file it came from, so
2660
- * the routes refuse it on a guide by name. A git-published artifact cannot
2661
- * drop its path either, because the published-source group is only legal
2662
- * beside one.
2663
- */
2664
- readonly path: v.OptionalSchema<v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 512, undefined>, v.CheckAction<string, "path must use forward slashes">, v.CheckAction<string, "path must be relative">, v.CheckAction<string, "path must not contain control characters">, v.CheckAction<string, "path must not contain empty, \".\" or \"..\" segments">]>, undefined>, undefined>;
2665
- readonly sourceItemIds: v.OptionalSchema<v.SchemaWithPipe<readonly [v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, undefined>, v.MaxLengthAction<string[], 100, undefined>]>, undefined>;
2666
- /**
2667
- * The revision this update's bytes were read from — same meaning as on
2668
- * `PushContextRequestSchema` above, and the field that makes a republication
2669
- * advance an artifact's provenance rather than leave it pointing at the
2670
- * commit it was first published from.
2671
- *
2672
- * **Omitted leaves the stored group alone; it never clears it.** An update
2673
- * that says nothing about provenance is a name or body edit, not a claim that
2674
- * the artifact stopped being git-owned — and an absent key that silently
2675
- * un-owned a row would hand a subscriber write access by omission, which is
2676
- * the failure the whole ownership model exists to prevent. Ownership is given
2677
- * up by promotion, not by a missing field.
2678
- */
2679
- readonly gitSource: v.OptionalSchema<v.ObjectSchema<{
2680
- /**
2681
- * The committed `project.id` of the source repository — the same id space as
2682
- * an item's delivery-scoping `projectId` below, but a different fact: that one
2683
- * says which repo an item is materialized into and is stamped onto
2684
- * Mossbear-owned rows too, this one says who may edit it.
2685
- */
2686
- readonly projectId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 128, undefined>, v.RegexAction<string, "projectId must contain only letters, digits, underscore, dot or hyphen">]>;
2687
- readonly commitSha: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "commitSha must be 40 or 64 lowercase hex characters">]>;
2688
- /**
2689
- * The branch the publishing commit was on. **The one optional member**:
2690
- * publication is not restricted by branch, so this is recorded so a subscriber
2691
- * can see what they got, and a detached HEAD has none to record.
2692
- */
2693
- readonly branch: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 255, undefined>]>, undefined>;
2694
- }, undefined>, undefined>;
2695
- /**
2696
- * Tombstone this artifact: the commit that published it has since deleted the
2697
- * file, so the revision stops being delivered while the row and its version
2698
- * history stay where they are.
2699
- *
2700
- * **A verb, not a column state**, the same shape the dashboard's own removal
2701
- * takes (`~/zero/mutators.ts` → `guideFiles.update`'s `removed`). There is no
2702
- * writable field here that a removal and an ordinary edit could disagree
2703
- * about, and `literal(true)` is what keeps `removed: false` from reading as a
2704
- * request to bring something back — un-removing is republishing, which is an
2705
- * ordinary content write.
2706
- *
2707
- * **`gitSource` is required alongside it and the route enforces that.** A
2708
- * tombstone's whole claim is *which revision removed the file*: without one
2709
- * the row would say an artifact stopped being delivered and be unable to say
2710
- * why, which is the silent withdrawal this field exists to replace. That also
2711
- * keeps the only writer of a removal here the publication path — this is not
2712
- * a general delete verb for the context layer.
2713
- *
2714
- * **Never sent with `content`.** A removal has no bytes; a body carrying both
2715
- * is two answers to one question and the route refuses it rather than picking.
2716
- */
2958
+ }, undefined>, v.TransformAction<{
2959
+ id: string;
2960
+ artifactId?: string | null | undefined;
2961
+ type?: string | undefined;
2962
+ name: string;
2963
+ role: string | null;
2964
+ format: string | null;
2965
+ content: string | null;
2966
+ origin?: string | null | undefined;
2967
+ version?: number | undefined;
2968
+ guideId?: string | null | undefined;
2969
+ root?: "project" | "global" | null | undefined;
2970
+ path?: string | null | undefined;
2971
+ projectId?: string | null | undefined;
2972
+ pathProjectId?: string | null | undefined;
2973
+ aliases?: {
2974
+ root: "project" | "global";
2975
+ path: string;
2976
+ }[] | undefined;
2977
+ comments?: {
2978
+ id: string;
2979
+ state?: "open" | "resolved" | undefined;
2980
+ passage?: {
2981
+ quote: string;
2982
+ status: "located" | "changed" | "orphaned";
2983
+ lines: {
2984
+ start: number;
2985
+ end: number;
2986
+ } | null;
2987
+ } | undefined;
2988
+ body: string;
2989
+ suggestion?: string | undefined;
2990
+ finding?: {
2991
+ tier: "observed" | "usage" | "practice";
2992
+ tierLine: string;
2993
+ blindSpot: string;
2994
+ prediction: string | null;
2995
+ } | undefined;
2996
+ approved?: boolean | undefined;
2997
+ authorName: string | null;
2998
+ createdAt: string;
2999
+ itemVersion: number;
3000
+ itemChangedSince: boolean;
3001
+ deliveredCount: number;
3002
+ threadId: string;
3003
+ replyToId: string | null;
3004
+ }[] | undefined;
3005
+ updatedAt: string;
3006
+ gitSource?: {
3007
+ projectId: string;
3008
+ commitSha: string;
3009
+ branch?: string | undefined;
3010
+ } | null | undefined;
3011
+ removed?: true | undefined;
3012
+ }, {
3013
+ type: string;
3014
+ id: string;
3015
+ artifactId?: string | null | undefined;
3016
+ name: string;
3017
+ role: string | null;
3018
+ format: string | null;
3019
+ content: string | null;
3020
+ origin?: string | null | undefined;
3021
+ version?: number | undefined;
3022
+ guideId?: string | null | undefined;
3023
+ root?: "project" | "global" | null | undefined;
3024
+ path?: string | null | undefined;
3025
+ projectId?: string | null | undefined;
3026
+ pathProjectId?: string | null | undefined;
3027
+ aliases?: {
3028
+ root: "project" | "global";
3029
+ path: string;
3030
+ }[] | undefined;
3031
+ comments?: {
3032
+ id: string;
3033
+ state?: "open" | "resolved" | undefined;
3034
+ passage?: {
3035
+ quote: string;
3036
+ status: "located" | "changed" | "orphaned";
3037
+ lines: {
3038
+ start: number;
3039
+ end: number;
3040
+ } | null;
3041
+ } | undefined;
3042
+ body: string;
3043
+ suggestion?: string | undefined;
3044
+ finding?: {
3045
+ tier: "observed" | "usage" | "practice";
3046
+ tierLine: string;
3047
+ blindSpot: string;
3048
+ prediction: string | null;
3049
+ } | undefined;
3050
+ approved?: boolean | undefined;
3051
+ authorName: string | null;
3052
+ createdAt: string;
3053
+ itemVersion: number;
3054
+ itemChangedSince: boolean;
3055
+ deliveredCount: number;
3056
+ threadId: string;
3057
+ replyToId: string | null;
3058
+ }[] | undefined;
3059
+ updatedAt: string;
3060
+ gitSource?: {
3061
+ projectId: string;
3062
+ commitSha: string;
3063
+ branch?: string | undefined;
3064
+ } | null | undefined;
3065
+ removed?: true | undefined;
3066
+ }>]>;
3067
+ readonly created: v.BooleanSchema<undefined>;
3068
+ }, undefined>;
3069
+ export declare const UpdateContextItemRequestSchema: v.ObjectSchema<{
3070
+ readonly itemId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
3071
+ readonly name: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 200, undefined>]>, undefined>;
3072
+ readonly content: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.CheckAction<string, "content must be at most 524288 bytes">]>, undefined>;
3073
+ readonly expectedVersion: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>, undefined>;
3074
+ /**
3075
+ * The committed `project.id` of the checkout this write comes from — same
3076
+ * meaning and same two uses as on `PushContextRequestSchema`: a bundle that
3077
+ * claims a home accepts writes only from that repo, and a request declaring
3078
+ * nothing is not it; and when this update sets `path`, it is stored as the
3079
+ * repo that path is placed in. Parsed as on `PushContextRequestSchema`.
3080
+ */
3081
+ readonly projectId: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>, undefined>;
3082
+ /**
3083
+ * Move the document: its new placement, or `null` to take the placement away
3084
+ * so it lands in the bundle folder again.
3085
+ *
3086
+ * **Three states, the same shape `sourceItemIds` takes.** Omitted leaves the
3087
+ * stored path and its home alone — every name or body edit. A path replaces
3088
+ * both: the path, and the home as `projectId` above declares it, since a path
3089
+ * is relative to the repo that declared it. `null` clears both.
3090
+ *
3091
+ * The same schema as the create side and the read side, for the reason
3092
+ * `PushContextRequestSchema` gives, and the same refusals in the routes —
3093
+ * agent guidance, Mossbear's state directory, git's.
3094
+ *
3095
+ * **Documents only.** A guide's path is its discovery path, which import
3096
+ * reconciles on; moving it here would fork it from the file it came from, so
3097
+ * the routes refuse it on a guide by name. A git-published artifact cannot
3098
+ * drop its path either, because the published-source group is only legal
3099
+ * beside one.
3100
+ */
3101
+ readonly path: v.OptionalSchema<v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 512, undefined>, v.CheckAction<string, "path must use forward slashes">, v.CheckAction<string, "path must be relative">, v.CheckAction<string, "path must not contain control characters">, v.CheckAction<string, "path must not contain empty, \".\" or \"..\" segments">]>, undefined>, undefined>;
3102
+ readonly sourceItemIds: v.OptionalSchema<v.SchemaWithPipe<readonly [v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, undefined>, v.MaxLengthAction<string[], 100, undefined>]>, undefined>;
3103
+ /**
3104
+ * The revision this update's bytes were read from — same meaning as on
3105
+ * `PushContextRequestSchema` above, and the field that makes a republication
3106
+ * advance an artifact's provenance rather than leave it pointing at the
3107
+ * commit it was first published from.
3108
+ *
3109
+ * **Omitted leaves the stored group alone; it never clears it.** An update
3110
+ * that says nothing about provenance is a name or body edit, not a claim that
3111
+ * the artifact stopped being git-owned — and an absent key that silently
3112
+ * un-owned a row would hand a subscriber write access by omission, which is
3113
+ * the failure the whole ownership model exists to prevent. Ownership is given
3114
+ * up by promotion, not by a missing field.
3115
+ */
3116
+ readonly gitSource: v.OptionalSchema<v.ObjectSchema<{
3117
+ /**
3118
+ * The committed `project.id` of the source repository — the same id space as
3119
+ * an item's delivery-scoping `projectId` below, but a different fact: that one
3120
+ * says which repo an item is materialized into and is stamped onto
3121
+ * Mossbear-owned rows too, this one says who may edit it.
3122
+ */
3123
+ readonly projectId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 128, undefined>, v.RegexAction<string, "projectId must contain only letters, digits, underscore, dot or hyphen">]>;
3124
+ readonly commitSha: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "commitSha must be 40 or 64 lowercase hex characters">]>;
3125
+ /**
3126
+ * The branch the publishing commit was on. **The one optional member**:
3127
+ * publication is not restricted by branch, so this is recorded so a subscriber
3128
+ * can see what they got, and a detached HEAD has none to record.
3129
+ */
3130
+ readonly branch: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 255, undefined>]>, undefined>;
3131
+ }, undefined>, undefined>;
3132
+ /**
3133
+ * Tombstone this artifact: the commit that published it has since deleted the
3134
+ * file, so the revision stops being delivered while the row and its version
3135
+ * history stay where they are.
3136
+ *
3137
+ * **A verb, not a column state**, the same shape the dashboard's own removal
3138
+ * takes (`~/zero/mutators.ts` → `guideFiles.update`'s `removed`). There is no
3139
+ * writable field here that a removal and an ordinary edit could disagree
3140
+ * about, and `literal(true)` is what keeps `removed: false` from reading as a
3141
+ * request to bring something back — un-removing is republishing, which is an
3142
+ * ordinary content write.
3143
+ *
3144
+ * **`gitSource` is required alongside it and the route enforces that.** A
3145
+ * tombstone's whole claim is *which revision removed the file*: without one
3146
+ * the row would say an artifact stopped being delivered and be unable to say
3147
+ * why, which is the silent withdrawal this field exists to replace. That also
3148
+ * keeps the only writer of a removal here the publication path — this is not
3149
+ * a general delete verb for the context layer.
3150
+ *
3151
+ * **Never sent with `content`.** A removal has no bytes; a body carrying both
3152
+ * is two answers to one question and the route refuses it rather than picking.
3153
+ */
2717
3154
  readonly removed: v.OptionalSchema<v.LiteralSchema<true, undefined>, undefined>;
2718
3155
  }, undefined>;
2719
3156
  export declare const UpdateContextItemResponseSchema: v.ObjectSchema<{
2720
- readonly item: v.ObjectSchema<{
3157
+ readonly item: v.SchemaWithPipe<readonly [v.ObjectSchema<{
2721
3158
  readonly id: v.StringSchema<undefined>;
2722
3159
  /**
2723
3160
  * The id every artifact route addresses: the body file's id for a guide
2724
3161
  * (null only for a guide with no body yet), the item's own id otherwise.
2725
- * Optional so a client tolerates a server that predates it.
3162
+ * Optional so a client tolerates a server that predates it, and one that
3163
+ * stops sending it (the item id is the artifact id).
2726
3164
  */
2727
3165
  readonly artifactId: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
2728
- readonly type: v.PicklistSchema<string[], undefined>;
3166
+ /**
3167
+ * Leaving the wire: a reader tells a guide from content by `role` and the
3168
+ * guide fields, not by this. Optional so a client parses a server that no
3169
+ * longer sends it.
3170
+ */
3171
+ readonly type: v.OptionalSchema<v.PicklistSchema<string[], undefined>, undefined>;
2729
3172
  readonly name: v.StringSchema<undefined>;
2730
3173
  /**
2731
3174
  * The stored `(role, format)` pair, as two bare nullable strings.
@@ -2977,65 +3420,173 @@ export declare const UpdateContextItemResponseSchema: v.ObjectSchema<{
2977
3420
  * than a tombstone that says no.
2978
3421
  */
2979
3422
  readonly removed: v.OptionalSchema<v.LiteralSchema<true, undefined>, undefined>;
2980
- }, undefined>;
2981
- readonly updated: v.BooleanSchema<undefined>;
2982
- }, undefined>;
2983
- export declare const UpdateContextItemBodySchema: Omit<v.ObjectSchema<{
2984
- readonly itemId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
2985
- readonly name: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 200, undefined>]>, undefined>;
2986
- readonly content: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.CheckAction<string, "content must be at most 524288 bytes">]>, undefined>;
2987
- readonly expectedVersion: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>, undefined>;
2988
- /**
2989
- * The committed `project.id` of the checkout this write comes from — same
2990
- * meaning and same two uses as on `PushContextRequestSchema`: a bundle that
2991
- * claims a home accepts writes only from that repo, and a request declaring
2992
- * nothing is not it; and when this update sets `path`, it is stored as the
2993
- * repo that path is placed in. Parsed as on `PushContextRequestSchema`.
2994
- */
2995
- readonly projectId: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>, undefined>;
2996
- /**
2997
- * Move the document: its new placement, or `null` to take the placement away
2998
- * so it lands in the bundle folder again.
2999
- *
3000
- * **Three states, the same shape `sourceItemIds` takes.** Omitted leaves the
3001
- * stored path and its home alone — every name or body edit. A path replaces
3002
- * both: the path, and the home as `projectId` above declares it, since a path
3003
- * is relative to the repo that declared it. `null` clears both.
3004
- *
3005
- * The same schema as the create side and the read side, for the reason
3006
- * `PushContextRequestSchema` gives, and the same refusals in the routes —
3007
- * agent guidance, Mossbear's state directory, git's.
3008
- *
3009
- * **Documents only.** A guide's path is its discovery path, which import
3010
- * reconciles on; moving it here would fork it from the file it came from, so
3011
- * the routes refuse it on a guide by name. A git-published artifact cannot
3012
- * drop its path either, because the published-source group is only legal
3013
- * beside one.
3014
- */
3015
- readonly path: v.OptionalSchema<v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 512, undefined>, v.CheckAction<string, "path must use forward slashes">, v.CheckAction<string, "path must be relative">, v.CheckAction<string, "path must not contain control characters">, v.CheckAction<string, "path must not contain empty, \".\" or \"..\" segments">]>, undefined>, undefined>;
3016
- readonly sourceItemIds: v.OptionalSchema<v.SchemaWithPipe<readonly [v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, undefined>, v.MaxLengthAction<string[], 100, undefined>]>, undefined>;
3017
- /**
3018
- * The revision this update's bytes were read from — same meaning as on
3019
- * `PushContextRequestSchema` above, and the field that makes a republication
3020
- * advance an artifact's provenance rather than leave it pointing at the
3021
- * commit it was first published from.
3022
- *
3023
- * **Omitted leaves the stored group alone; it never clears it.** An update
3024
- * that says nothing about provenance is a name or body edit, not a claim that
3025
- * the artifact stopped being git-owned — and an absent key that silently
3026
- * un-owned a row would hand a subscriber write access by omission, which is
3027
- * the failure the whole ownership model exists to prevent. Ownership is given
3028
- * up by promotion, not by a missing field.
3029
- */
3030
- readonly gitSource: v.OptionalSchema<v.ObjectSchema<{
3031
- /**
3032
- * The committed `project.id` of the source repository — the same id space as
3033
- * an item's delivery-scoping `projectId` below, but a different fact: that one
3034
- * says which repo an item is materialized into and is stamped onto
3035
- * Mossbear-owned rows too, this one says who may edit it.
3036
- */
3037
- readonly projectId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 128, undefined>, v.RegexAction<string, "projectId must contain only letters, digits, underscore, dot or hyphen">]>;
3038
- readonly commitSha: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "commitSha must be 40 or 64 lowercase hex characters">]>;
3423
+ }, undefined>, v.TransformAction<{
3424
+ id: string;
3425
+ artifactId?: string | null | undefined;
3426
+ type?: string | undefined;
3427
+ name: string;
3428
+ role: string | null;
3429
+ format: string | null;
3430
+ content: string | null;
3431
+ origin?: string | null | undefined;
3432
+ version?: number | undefined;
3433
+ guideId?: string | null | undefined;
3434
+ root?: "project" | "global" | null | undefined;
3435
+ path?: string | null | undefined;
3436
+ projectId?: string | null | undefined;
3437
+ pathProjectId?: string | null | undefined;
3438
+ aliases?: {
3439
+ root: "project" | "global";
3440
+ path: string;
3441
+ }[] | undefined;
3442
+ comments?: {
3443
+ id: string;
3444
+ state?: "open" | "resolved" | undefined;
3445
+ passage?: {
3446
+ quote: string;
3447
+ status: "located" | "changed" | "orphaned";
3448
+ lines: {
3449
+ start: number;
3450
+ end: number;
3451
+ } | null;
3452
+ } | undefined;
3453
+ body: string;
3454
+ suggestion?: string | undefined;
3455
+ finding?: {
3456
+ tier: "observed" | "usage" | "practice";
3457
+ tierLine: string;
3458
+ blindSpot: string;
3459
+ prediction: string | null;
3460
+ } | undefined;
3461
+ approved?: boolean | undefined;
3462
+ authorName: string | null;
3463
+ createdAt: string;
3464
+ itemVersion: number;
3465
+ itemChangedSince: boolean;
3466
+ deliveredCount: number;
3467
+ threadId: string;
3468
+ replyToId: string | null;
3469
+ }[] | undefined;
3470
+ updatedAt: string;
3471
+ gitSource?: {
3472
+ projectId: string;
3473
+ commitSha: string;
3474
+ branch?: string | undefined;
3475
+ } | null | undefined;
3476
+ removed?: true | undefined;
3477
+ }, {
3478
+ type: string;
3479
+ id: string;
3480
+ artifactId?: string | null | undefined;
3481
+ name: string;
3482
+ role: string | null;
3483
+ format: string | null;
3484
+ content: string | null;
3485
+ origin?: string | null | undefined;
3486
+ version?: number | undefined;
3487
+ guideId?: string | null | undefined;
3488
+ root?: "project" | "global" | null | undefined;
3489
+ path?: string | null | undefined;
3490
+ projectId?: string | null | undefined;
3491
+ pathProjectId?: string | null | undefined;
3492
+ aliases?: {
3493
+ root: "project" | "global";
3494
+ path: string;
3495
+ }[] | undefined;
3496
+ comments?: {
3497
+ id: string;
3498
+ state?: "open" | "resolved" | undefined;
3499
+ passage?: {
3500
+ quote: string;
3501
+ status: "located" | "changed" | "orphaned";
3502
+ lines: {
3503
+ start: number;
3504
+ end: number;
3505
+ } | null;
3506
+ } | undefined;
3507
+ body: string;
3508
+ suggestion?: string | undefined;
3509
+ finding?: {
3510
+ tier: "observed" | "usage" | "practice";
3511
+ tierLine: string;
3512
+ blindSpot: string;
3513
+ prediction: string | null;
3514
+ } | undefined;
3515
+ approved?: boolean | undefined;
3516
+ authorName: string | null;
3517
+ createdAt: string;
3518
+ itemVersion: number;
3519
+ itemChangedSince: boolean;
3520
+ deliveredCount: number;
3521
+ threadId: string;
3522
+ replyToId: string | null;
3523
+ }[] | undefined;
3524
+ updatedAt: string;
3525
+ gitSource?: {
3526
+ projectId: string;
3527
+ commitSha: string;
3528
+ branch?: string | undefined;
3529
+ } | null | undefined;
3530
+ removed?: true | undefined;
3531
+ }>]>;
3532
+ readonly updated: v.BooleanSchema<undefined>;
3533
+ }, undefined>;
3534
+ export declare const UpdateContextItemBodySchema: Omit<v.ObjectSchema<{
3535
+ readonly itemId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
3536
+ readonly name: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 200, undefined>]>, undefined>;
3537
+ readonly content: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.CheckAction<string, "content must be at most 524288 bytes">]>, undefined>;
3538
+ readonly expectedVersion: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>, undefined>;
3539
+ /**
3540
+ * The committed `project.id` of the checkout this write comes from — same
3541
+ * meaning and same two uses as on `PushContextRequestSchema`: a bundle that
3542
+ * claims a home accepts writes only from that repo, and a request declaring
3543
+ * nothing is not it; and when this update sets `path`, it is stored as the
3544
+ * repo that path is placed in. Parsed as on `PushContextRequestSchema`.
3545
+ */
3546
+ readonly projectId: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>, undefined>;
3547
+ /**
3548
+ * Move the document: its new placement, or `null` to take the placement away
3549
+ * so it lands in the bundle folder again.
3550
+ *
3551
+ * **Three states, the same shape `sourceItemIds` takes.** Omitted leaves the
3552
+ * stored path and its home alone — every name or body edit. A path replaces
3553
+ * both: the path, and the home as `projectId` above declares it, since a path
3554
+ * is relative to the repo that declared it. `null` clears both.
3555
+ *
3556
+ * The same schema as the create side and the read side, for the reason
3557
+ * `PushContextRequestSchema` gives, and the same refusals in the routes —
3558
+ * agent guidance, Mossbear's state directory, git's.
3559
+ *
3560
+ * **Documents only.** A guide's path is its discovery path, which import
3561
+ * reconciles on; moving it here would fork it from the file it came from, so
3562
+ * the routes refuse it on a guide by name. A git-published artifact cannot
3563
+ * drop its path either, because the published-source group is only legal
3564
+ * beside one.
3565
+ */
3566
+ readonly path: v.OptionalSchema<v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 512, undefined>, v.CheckAction<string, "path must use forward slashes">, v.CheckAction<string, "path must be relative">, v.CheckAction<string, "path must not contain control characters">, v.CheckAction<string, "path must not contain empty, \".\" or \"..\" segments">]>, undefined>, undefined>;
3567
+ readonly sourceItemIds: v.OptionalSchema<v.SchemaWithPipe<readonly [v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, undefined>, v.MaxLengthAction<string[], 100, undefined>]>, undefined>;
3568
+ /**
3569
+ * The revision this update's bytes were read from — same meaning as on
3570
+ * `PushContextRequestSchema` above, and the field that makes a republication
3571
+ * advance an artifact's provenance rather than leave it pointing at the
3572
+ * commit it was first published from.
3573
+ *
3574
+ * **Omitted leaves the stored group alone; it never clears it.** An update
3575
+ * that says nothing about provenance is a name or body edit, not a claim that
3576
+ * the artifact stopped being git-owned — and an absent key that silently
3577
+ * un-owned a row would hand a subscriber write access by omission, which is
3578
+ * the failure the whole ownership model exists to prevent. Ownership is given
3579
+ * up by promotion, not by a missing field.
3580
+ */
3581
+ readonly gitSource: v.OptionalSchema<v.ObjectSchema<{
3582
+ /**
3583
+ * The committed `project.id` of the source repository — the same id space as
3584
+ * an item's delivery-scoping `projectId` below, but a different fact: that one
3585
+ * says which repo an item is materialized into and is stamped onto
3586
+ * Mossbear-owned rows too, this one says who may edit it.
3587
+ */
3588
+ readonly projectId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 128, undefined>, v.RegexAction<string, "projectId must contain only letters, digits, underscore, dot or hyphen">]>;
3589
+ readonly commitSha: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "commitSha must be 40 or 64 lowercase hex characters">]>;
3039
3590
  /**
3040
3591
  * The branch the publishing commit was on. **The one optional member**:
3041
3592
  * publication is not restricted by branch, so this is recorded so a subscriber
@@ -3229,15 +3780,21 @@ export declare const UpdateContextItemBodySchema: Omit<v.ObjectSchema<{
3229
3780
  };
3230
3781
  /** A single canonical item, for the item-scoped read route. */
3231
3782
  export declare const ContextItemResponseSchema: v.ObjectSchema<{
3232
- readonly item: v.ObjectSchema<{
3783
+ readonly item: v.SchemaWithPipe<readonly [v.ObjectSchema<{
3233
3784
  readonly id: v.StringSchema<undefined>;
3234
3785
  /**
3235
3786
  * The id every artifact route addresses: the body file's id for a guide
3236
3787
  * (null only for a guide with no body yet), the item's own id otherwise.
3237
- * Optional so a client tolerates a server that predates it.
3788
+ * Optional so a client tolerates a server that predates it, and one that
3789
+ * stops sending it (the item id is the artifact id).
3238
3790
  */
3239
3791
  readonly artifactId: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
3240
- readonly type: v.PicklistSchema<string[], undefined>;
3792
+ /**
3793
+ * Leaving the wire: a reader tells a guide from content by `role` and the
3794
+ * guide fields, not by this. Optional so a client parses a server that no
3795
+ * longer sends it.
3796
+ */
3797
+ readonly type: v.OptionalSchema<v.PicklistSchema<string[], undefined>, undefined>;
3241
3798
  readonly name: v.StringSchema<undefined>;
3242
3799
  /**
3243
3800
  * The stored `(role, format)` pair, as two bare nullable strings.
@@ -3489,19 +4046,133 @@ export declare const ContextItemResponseSchema: v.ObjectSchema<{
3489
4046
  * than a tombstone that says no.
3490
4047
  */
3491
4048
  readonly removed: v.OptionalSchema<v.LiteralSchema<true, undefined>, undefined>;
3492
- }, undefined>;
4049
+ }, undefined>, v.TransformAction<{
4050
+ id: string;
4051
+ artifactId?: string | null | undefined;
4052
+ type?: string | undefined;
4053
+ name: string;
4054
+ role: string | null;
4055
+ format: string | null;
4056
+ content: string | null;
4057
+ origin?: string | null | undefined;
4058
+ version?: number | undefined;
4059
+ guideId?: string | null | undefined;
4060
+ root?: "project" | "global" | null | undefined;
4061
+ path?: string | null | undefined;
4062
+ projectId?: string | null | undefined;
4063
+ pathProjectId?: string | null | undefined;
4064
+ aliases?: {
4065
+ root: "project" | "global";
4066
+ path: string;
4067
+ }[] | undefined;
4068
+ comments?: {
4069
+ id: string;
4070
+ state?: "open" | "resolved" | undefined;
4071
+ passage?: {
4072
+ quote: string;
4073
+ status: "located" | "changed" | "orphaned";
4074
+ lines: {
4075
+ start: number;
4076
+ end: number;
4077
+ } | null;
4078
+ } | undefined;
4079
+ body: string;
4080
+ suggestion?: string | undefined;
4081
+ finding?: {
4082
+ tier: "observed" | "usage" | "practice";
4083
+ tierLine: string;
4084
+ blindSpot: string;
4085
+ prediction: string | null;
4086
+ } | undefined;
4087
+ approved?: boolean | undefined;
4088
+ authorName: string | null;
4089
+ createdAt: string;
4090
+ itemVersion: number;
4091
+ itemChangedSince: boolean;
4092
+ deliveredCount: number;
4093
+ threadId: string;
4094
+ replyToId: string | null;
4095
+ }[] | undefined;
4096
+ updatedAt: string;
4097
+ gitSource?: {
4098
+ projectId: string;
4099
+ commitSha: string;
4100
+ branch?: string | undefined;
4101
+ } | null | undefined;
4102
+ removed?: true | undefined;
4103
+ }, {
4104
+ type: string;
4105
+ id: string;
4106
+ artifactId?: string | null | undefined;
4107
+ name: string;
4108
+ role: string | null;
4109
+ format: string | null;
4110
+ content: string | null;
4111
+ origin?: string | null | undefined;
4112
+ version?: number | undefined;
4113
+ guideId?: string | null | undefined;
4114
+ root?: "project" | "global" | null | undefined;
4115
+ path?: string | null | undefined;
4116
+ projectId?: string | null | undefined;
4117
+ pathProjectId?: string | null | undefined;
4118
+ aliases?: {
4119
+ root: "project" | "global";
4120
+ path: string;
4121
+ }[] | undefined;
4122
+ comments?: {
4123
+ id: string;
4124
+ state?: "open" | "resolved" | undefined;
4125
+ passage?: {
4126
+ quote: string;
4127
+ status: "located" | "changed" | "orphaned";
4128
+ lines: {
4129
+ start: number;
4130
+ end: number;
4131
+ } | null;
4132
+ } | undefined;
4133
+ body: string;
4134
+ suggestion?: string | undefined;
4135
+ finding?: {
4136
+ tier: "observed" | "usage" | "practice";
4137
+ tierLine: string;
4138
+ blindSpot: string;
4139
+ prediction: string | null;
4140
+ } | undefined;
4141
+ approved?: boolean | undefined;
4142
+ authorName: string | null;
4143
+ createdAt: string;
4144
+ itemVersion: number;
4145
+ itemChangedSince: boolean;
4146
+ deliveredCount: number;
4147
+ threadId: string;
4148
+ replyToId: string | null;
4149
+ }[] | undefined;
4150
+ updatedAt: string;
4151
+ gitSource?: {
4152
+ projectId: string;
4153
+ commitSha: string;
4154
+ branch?: string | undefined;
4155
+ } | null | undefined;
4156
+ removed?: true | undefined;
4157
+ }>]>;
3493
4158
  }, undefined>;
3494
4159
  export declare const ArchiveContextItemResponseSchema: v.ObjectSchema<{
3495
4160
  readonly archived: v.BooleanSchema<undefined>;
3496
- readonly item: v.ObjectSchema<{
4161
+ readonly item: v.SchemaWithPipe<readonly [v.ObjectSchema<{
3497
4162
  readonly id: v.StringSchema<undefined>;
3498
4163
  /**
3499
4164
  * The id every artifact route addresses: the body file's id for a guide
3500
4165
  * (null only for a guide with no body yet), the item's own id otherwise.
3501
- * Optional so a client tolerates a server that predates it.
4166
+ * Optional so a client tolerates a server that predates it, and one that
4167
+ * stops sending it (the item id is the artifact id).
3502
4168
  */
3503
4169
  readonly artifactId: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
3504
- readonly type: v.PicklistSchema<string[], undefined>;
4170
+ /**
4171
+ * Leaving the wire: a reader tells a guide from content by `role` and the
4172
+ * guide fields, not by this. Optional so a client parses a server that no
4173
+ * longer sends it.
4174
+ */
4175
+ readonly type: v.OptionalSchema<v.PicklistSchema<string[], undefined>, undefined>;
3505
4176
  readonly name: v.StringSchema<undefined>;
3506
4177
  /**
3507
4178
  * The stored `(role, format)` pair, as two bare nullable strings.
@@ -3684,76 +4355,184 @@ export declare const ArchiveContextItemResponseSchema: v.ObjectSchema<{
3684
4355
  deliveredCount: number;
3685
4356
  threadId: string;
3686
4357
  replyToId: string | null;
3687
- }[], 20, undefined>]>, undefined>;
3688
- readonly updatedAt: v.StringSchema<undefined>;
3689
- /**
3690
- * Present iff this artifact is owned by git. Absent means Mossbear owns it
3691
- * and it is editable in the dashboard.
3692
- *
3693
- * **Optional, and absence is not yet a verdict.** Nothing writes this before
3694
- * `publish` ships, so today every item omits it, and the existing bundle-home
3695
- * rule — a bundle may name one repo as its only writer, and the server
3696
- * refuses every other writer by name — is what still protects items a repo
3697
- * already owns. A reader must not treat an absent `gitSource` as permission
3698
- * to publish back.
3699
- *
3700
- * **Optional *and* nullable, like every other late-added column on this item.**
3701
- * A serializer that maps the columns straight through emits `null` for a
3702
- * Mossbear-owned row, and a key that only accepted `undefined` would throw on
3703
- * the whole response rather than on the one item — `parseContextItemsResponse`
3704
- * parses a pull as a batch. Both spellings read the same way: no git source.
3705
- *
3706
- * **`path` is the third required member of the subset and is not re-checked
3707
- * here.** The database holds that invariant
3708
- * (`guide_files_git_source_subset`), and a wire rule that looked identical
3709
- * would in fact be stricter: `path` is serialized through a scope helper that
3710
- * emits `null` for a path this schema cannot parse, so a single such row would
3711
- * fail every other item in the same pull. A git-owned item that arrives
3712
- * without a usable path is a broken item, not a broken response.
3713
- */
3714
- readonly gitSource: v.OptionalSchema<v.NullableSchema<v.ObjectSchema<{
3715
- /**
3716
- * The committed `project.id` of the source repository — the same id space as
3717
- * an item's delivery-scoping `projectId` below, but a different fact: that one
3718
- * says which repo an item is materialized into and is stamped onto
3719
- * Mossbear-owned rows too, this one says who may edit it.
3720
- */
3721
- readonly projectId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 128, undefined>, v.RegexAction<string, "projectId must contain only letters, digits, underscore, dot or hyphen">]>;
3722
- readonly commitSha: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "commitSha must be 40 or 64 lowercase hex characters">]>;
3723
- /**
3724
- * The branch the publishing commit was on. **The one optional member**:
3725
- * publication is not restricted by branch, so this is recorded so a subscriber
3726
- * can see what they got, and a detached HEAD has none to record.
3727
- */
3728
- readonly branch: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 255, undefined>]>, undefined>;
3729
- }, undefined>, undefined>, undefined>;
3730
- /**
3731
- * This artifact is a **tombstone**: the repository that publishes it deleted
3732
- * the file, so what the item still carries is the last revision rather than a
3733
- * current one (`artifact-ownership-and-delivery-plan.md` → D28).
3734
- *
3735
- * **It is still delivered, and that is deliberate.** Dropping the item from
3736
- * the response would say the same thing more quietly and cost two things
3737
- * worth more than the byte: the publishing repo would lose the id it needs to
3738
- * republish the path in place — re-adding a deleted file would create a
3739
- * second artifact at the same path rather than a new revision of the one
3740
- * that is there — and a reader would be left unable to tell a removal from
3741
- * a bundle it has stopped being able to see. What the flag asks of a client
3742
- * is one thing: do not materialize it. A file left at a discovery root keeps
3743
- * feeding deleted guidance into every agent that reads that repo, which is
3744
- * the failure the decision exists to stop.
3745
- *
3746
- * **Optional, and absent means an ordinary artifact.** A client that has
3747
- * never heard of it behaves as it always did — it keeps the last published
3748
- * revision on disk, which is the retain behaviour this replaces rather than a
3749
- * new failure. That is what makes the server safe to ship first.
3750
- *
3751
- * `literal(true)` rather than a boolean: `removed: false` would be a second
3752
- * spelling of absence, and an artifact that came back is content again rather
3753
- * than a tombstone that says no.
3754
- */
3755
- readonly removed: v.OptionalSchema<v.LiteralSchema<true, undefined>, undefined>;
3756
- }, undefined>;
4358
+ }[], 20, undefined>]>, undefined>;
4359
+ readonly updatedAt: v.StringSchema<undefined>;
4360
+ /**
4361
+ * Present iff this artifact is owned by git. Absent means Mossbear owns it
4362
+ * and it is editable in the dashboard.
4363
+ *
4364
+ * **Optional, and absence is not yet a verdict.** Nothing writes this before
4365
+ * `publish` ships, so today every item omits it, and the existing bundle-home
4366
+ * rule — a bundle may name one repo as its only writer, and the server
4367
+ * refuses every other writer by name — is what still protects items a repo
4368
+ * already owns. A reader must not treat an absent `gitSource` as permission
4369
+ * to publish back.
4370
+ *
4371
+ * **Optional *and* nullable, like every other late-added column on this item.**
4372
+ * A serializer that maps the columns straight through emits `null` for a
4373
+ * Mossbear-owned row, and a key that only accepted `undefined` would throw on
4374
+ * the whole response rather than on the one item — `parseContextItemsResponse`
4375
+ * parses a pull as a batch. Both spellings read the same way: no git source.
4376
+ *
4377
+ * **`path` is the third required member of the subset and is not re-checked
4378
+ * here.** The database holds that invariant
4379
+ * (`guide_files_git_source_subset`), and a wire rule that looked identical
4380
+ * would in fact be stricter: `path` is serialized through a scope helper that
4381
+ * emits `null` for a path this schema cannot parse, so a single such row would
4382
+ * fail every other item in the same pull. A git-owned item that arrives
4383
+ * without a usable path is a broken item, not a broken response.
4384
+ */
4385
+ readonly gitSource: v.OptionalSchema<v.NullableSchema<v.ObjectSchema<{
4386
+ /**
4387
+ * The committed `project.id` of the source repository — the same id space as
4388
+ * an item's delivery-scoping `projectId` below, but a different fact: that one
4389
+ * says which repo an item is materialized into and is stamped onto
4390
+ * Mossbear-owned rows too, this one says who may edit it.
4391
+ */
4392
+ readonly projectId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 128, undefined>, v.RegexAction<string, "projectId must contain only letters, digits, underscore, dot or hyphen">]>;
4393
+ readonly commitSha: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "commitSha must be 40 or 64 lowercase hex characters">]>;
4394
+ /**
4395
+ * The branch the publishing commit was on. **The one optional member**:
4396
+ * publication is not restricted by branch, so this is recorded so a subscriber
4397
+ * can see what they got, and a detached HEAD has none to record.
4398
+ */
4399
+ readonly branch: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 255, undefined>]>, undefined>;
4400
+ }, undefined>, undefined>, undefined>;
4401
+ /**
4402
+ * This artifact is a **tombstone**: the repository that publishes it deleted
4403
+ * the file, so what the item still carries is the last revision rather than a
4404
+ * current one (`artifact-ownership-and-delivery-plan.md` → D28).
4405
+ *
4406
+ * **It is still delivered, and that is deliberate.** Dropping the item from
4407
+ * the response would say the same thing more quietly and cost two things
4408
+ * worth more than the byte: the publishing repo would lose the id it needs to
4409
+ * republish the path in place — re-adding a deleted file would create a
4410
+ * second artifact at the same path rather than a new revision of the one
4411
+ * that is there — and a reader would be left unable to tell a removal from
4412
+ * a bundle it has stopped being able to see. What the flag asks of a client
4413
+ * is one thing: do not materialize it. A file left at a discovery root keeps
4414
+ * feeding deleted guidance into every agent that reads that repo, which is
4415
+ * the failure the decision exists to stop.
4416
+ *
4417
+ * **Optional, and absent means an ordinary artifact.** A client that has
4418
+ * never heard of it behaves as it always did — it keeps the last published
4419
+ * revision on disk, which is the retain behaviour this replaces rather than a
4420
+ * new failure. That is what makes the server safe to ship first.
4421
+ *
4422
+ * `literal(true)` rather than a boolean: `removed: false` would be a second
4423
+ * spelling of absence, and an artifact that came back is content again rather
4424
+ * than a tombstone that says no.
4425
+ */
4426
+ readonly removed: v.OptionalSchema<v.LiteralSchema<true, undefined>, undefined>;
4427
+ }, undefined>, v.TransformAction<{
4428
+ id: string;
4429
+ artifactId?: string | null | undefined;
4430
+ type?: string | undefined;
4431
+ name: string;
4432
+ role: string | null;
4433
+ format: string | null;
4434
+ content: string | null;
4435
+ origin?: string | null | undefined;
4436
+ version?: number | undefined;
4437
+ guideId?: string | null | undefined;
4438
+ root?: "project" | "global" | null | undefined;
4439
+ path?: string | null | undefined;
4440
+ projectId?: string | null | undefined;
4441
+ pathProjectId?: string | null | undefined;
4442
+ aliases?: {
4443
+ root: "project" | "global";
4444
+ path: string;
4445
+ }[] | undefined;
4446
+ comments?: {
4447
+ id: string;
4448
+ state?: "open" | "resolved" | undefined;
4449
+ passage?: {
4450
+ quote: string;
4451
+ status: "located" | "changed" | "orphaned";
4452
+ lines: {
4453
+ start: number;
4454
+ end: number;
4455
+ } | null;
4456
+ } | undefined;
4457
+ body: string;
4458
+ suggestion?: string | undefined;
4459
+ finding?: {
4460
+ tier: "observed" | "usage" | "practice";
4461
+ tierLine: string;
4462
+ blindSpot: string;
4463
+ prediction: string | null;
4464
+ } | undefined;
4465
+ approved?: boolean | undefined;
4466
+ authorName: string | null;
4467
+ createdAt: string;
4468
+ itemVersion: number;
4469
+ itemChangedSince: boolean;
4470
+ deliveredCount: number;
4471
+ threadId: string;
4472
+ replyToId: string | null;
4473
+ }[] | undefined;
4474
+ updatedAt: string;
4475
+ gitSource?: {
4476
+ projectId: string;
4477
+ commitSha: string;
4478
+ branch?: string | undefined;
4479
+ } | null | undefined;
4480
+ removed?: true | undefined;
4481
+ }, {
4482
+ type: string;
4483
+ id: string;
4484
+ artifactId?: string | null | undefined;
4485
+ name: string;
4486
+ role: string | null;
4487
+ format: string | null;
4488
+ content: string | null;
4489
+ origin?: string | null | undefined;
4490
+ version?: number | undefined;
4491
+ guideId?: string | null | undefined;
4492
+ root?: "project" | "global" | null | undefined;
4493
+ path?: string | null | undefined;
4494
+ projectId?: string | null | undefined;
4495
+ pathProjectId?: string | null | undefined;
4496
+ aliases?: {
4497
+ root: "project" | "global";
4498
+ path: string;
4499
+ }[] | undefined;
4500
+ comments?: {
4501
+ id: string;
4502
+ state?: "open" | "resolved" | undefined;
4503
+ passage?: {
4504
+ quote: string;
4505
+ status: "located" | "changed" | "orphaned";
4506
+ lines: {
4507
+ start: number;
4508
+ end: number;
4509
+ } | null;
4510
+ } | undefined;
4511
+ body: string;
4512
+ suggestion?: string | undefined;
4513
+ finding?: {
4514
+ tier: "observed" | "usage" | "practice";
4515
+ tierLine: string;
4516
+ blindSpot: string;
4517
+ prediction: string | null;
4518
+ } | undefined;
4519
+ approved?: boolean | undefined;
4520
+ authorName: string | null;
4521
+ createdAt: string;
4522
+ itemVersion: number;
4523
+ itemChangedSince: boolean;
4524
+ deliveredCount: number;
4525
+ threadId: string;
4526
+ replyToId: string | null;
4527
+ }[] | undefined;
4528
+ updatedAt: string;
4529
+ gitSource?: {
4530
+ projectId: string;
4531
+ commitSha: string;
4532
+ branch?: string | undefined;
4533
+ } | null | undefined;
4534
+ removed?: true | undefined;
4535
+ }>]>;
3757
4536
  }, undefined>;
3758
4537
  export declare const CaptureIdSchema: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 8, "id must be at least 8 characters">, v.MaxLengthAction<string, 128, undefined>, v.RegexAction<string, "id must contain only letters, digits, underscore, dot or hyphen">]>;
3759
4538
  export declare const InboxCaptureRequestSchema: v.ObjectSchema<{
@@ -3828,6 +4607,24 @@ export declare const InboxArchiveRequestSchema: v.ObjectSchema<{
3828
4607
  export declare const InboxArchiveResponseSchema: v.ObjectSchema<{
3829
4608
  readonly archived: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
3830
4609
  }, undefined>;
4610
+ export declare const ArtifactVersionSchema: v.ObjectSchema<{
4611
+ readonly id: v.StringSchema<undefined>;
4612
+ readonly version: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>;
4613
+ readonly contentHash: v.StringSchema<undefined>;
4614
+ readonly authorType: v.StringSchema<undefined>;
4615
+ readonly metadata: v.OptionalSchema<v.NullableSchema<v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>, undefined>, undefined>;
4616
+ readonly createdAt: v.StringSchema<undefined>;
4617
+ }, undefined>;
4618
+ export declare const ArtifactVersionDetailSchema: v.ObjectSchema<{
4619
+ readonly id: v.StringSchema<undefined>;
4620
+ readonly version: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>;
4621
+ readonly content: v.NullableSchema<v.StringSchema<undefined>, undefined>;
4622
+ readonly contentHash: v.StringSchema<undefined>;
4623
+ readonly authorType: v.StringSchema<undefined>;
4624
+ readonly metadata: v.OptionalSchema<v.NullableSchema<v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>, undefined>, undefined>;
4625
+ readonly createdAt: v.StringSchema<undefined>;
4626
+ }, undefined>;
4627
+ /** The item routes' names for the version schemas, kept while those routes are served. */
3831
4628
  export declare const ContextItemVersionSchema: v.ObjectSchema<{
3832
4629
  readonly id: v.StringSchema<undefined>;
3833
4630
  readonly version: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>;
@@ -4323,13 +5120,11 @@ export declare const UpdateArtifactRequestSchema: v.StrictObjectSchema<{
4323
5120
  * The writer's checkout, as the `project.id` it commits. Declaring it grants
4324
5121
  * nothing; it says which checkout this write comes from, so the home
4325
5122
  * repository of a git-owned artifact or home-claiming bundle is not refused.
4326
- * Same meaning and parsing as `UpdateContextItemRequestSchema.projectId`.
4327
5123
  */
4328
5124
  readonly projectId: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>, undefined>;
4329
5125
  /**
4330
- * The commit the new content was read from, for a git-owned artifact. Same
4331
- * shape and meaning as `UpdateContextItemRequestSchema.gitSource`: it advances
4332
- * the artifact's recorded provenance with its content. A git-owned artifact
5126
+ * The commit the new content was read from, for a git-owned artifact. It
5127
+ * advances the artifact's recorded provenance with its content. A git-owned artifact
4333
5128
  * updated without one is refused (409). For any other artifact it is a
4334
5129
  * publication claim: sent beside a path, it makes git the owner from that
4335
5130
  * revision on, exactly as the bundle-scoped update it replaces did; sent for
@@ -6692,7 +7487,7 @@ export type ArtifactGradingUnavailable = v.InferOutput<typeof ArtifactGradingUna
6692
7487
  /**
6693
7488
  * What people, agents and grading have said about one artifact.
6694
7489
  *
6695
- * `grading` is the `guide_history` payload for the same guide and caller, or
7490
+ * `grading` is the guide's grading record for the same caller (the guide history route's payload), or
6696
7491
  * null with `gradingUnavailable` saying why. It is never a zeroed record:
6697
7492
  * absence is not a verdict. Comment evidence is never inlined.
6698
7493
  */
@@ -7319,6 +8114,20 @@ export type SearchCommentAuthorKind = v.InferOutput<typeof SearchCommentAuthorKi
7319
8114
  export declare const SEARCH_COMMENT_SUBJECT_KINDS: readonly ["item", "session"];
7320
8115
  export declare const SearchCommentSubjectKindSchema: v.PicklistSchema<readonly ["item", "session"], undefined>;
7321
8116
  export type SearchCommentSubjectKind = v.InferOutput<typeof SearchCommentSubjectKindSchema>;
8117
+ /**
8118
+ * The subject kinds a client names in a search: `artifact`, never its older
8119
+ * name `item`.
8120
+ */
8121
+ export declare const SEARCH_COMMENT_SUBJECT_KIND_NAMES: readonly ["artifact", "session"];
8122
+ export type SearchCommentSubjectKindName = (typeof SEARCH_COMMENT_SUBJECT_KIND_NAMES)[number];
8123
+ /**
8124
+ * The subject kinds a search request may name. `artifact` is the new name for
8125
+ * `item` and means the same subjects; both are accepted until every client sends
8126
+ * `artifact`, while hits and the advertised list above still say `item`.
8127
+ */
8128
+ export declare const SEARCH_COMMENT_SUBJECT_KIND_FILTERS: readonly ["item", "session", "artifact"];
8129
+ export declare const SearchCommentSubjectKindFilterSchema: v.PicklistSchema<readonly ["item", "session", "artifact"], undefined>;
8130
+ export type SearchCommentSubjectKindFilter = v.InferOutput<typeof SearchCommentSubjectKindFilterSchema>;
7322
8131
  /**
7323
8132
  * What a user turn was, as the session classifier labels it. The same
7324
8133
  * vocabulary the classifier writes; a `turns` search may keep only some.
@@ -7373,7 +8182,7 @@ export declare const SearchRequestObjectSchema: v.ObjectSchema<{
7373
8182
  * Restrict the `comments` corpus to comments on these kinds of subject. Does
7374
8183
  * not touch other corpora.
7375
8184
  */
7376
- readonly subjectKinds: v.OptionalSchema<v.SchemaWithPipe<readonly [v.ArraySchema<v.PicklistSchema<readonly ["item", "session"], undefined>, undefined>, v.MinLengthAction<("item" | "session")[], 1, undefined>]>, undefined>;
8185
+ readonly subjectKinds: v.OptionalSchema<v.SchemaWithPipe<readonly [v.ArraySchema<v.PicklistSchema<readonly ["item", "session", "artifact"], undefined>, undefined>, v.MinLengthAction<("item" | "artifact" | "session")[], 1, undefined>]>, undefined>;
7377
8186
  /**
7378
8187
  * Restrict the `turns` corpus to turns the classifier gave one of these
7379
8188
  * labels. A turn with no label never matches. Does not touch other corpora.
@@ -7443,7 +8252,7 @@ export declare const SearchRequestSchema: v.SchemaWithPipe<readonly [v.ObjectSch
7443
8252
  * Restrict the `comments` corpus to comments on these kinds of subject. Does
7444
8253
  * not touch other corpora.
7445
8254
  */
7446
- readonly subjectKinds: v.OptionalSchema<v.SchemaWithPipe<readonly [v.ArraySchema<v.PicklistSchema<readonly ["item", "session"], undefined>, undefined>, v.MinLengthAction<("item" | "session")[], 1, undefined>]>, undefined>;
8255
+ readonly subjectKinds: v.OptionalSchema<v.SchemaWithPipe<readonly [v.ArraySchema<v.PicklistSchema<readonly ["item", "session", "artifact"], undefined>, undefined>, v.MinLengthAction<("item" | "artifact" | "session")[], 1, undefined>]>, undefined>;
7447
8256
  /**
7448
8257
  * Restrict the `turns` corpus to turns the classifier gave one of these
7449
8258
  * labels. A turn with no label never matches. Does not touch other corpora.
@@ -7478,7 +8287,7 @@ export declare const SearchRequestSchema: v.SchemaWithPipe<readonly [v.ObjectSch
7478
8287
  [x: string]: string;
7479
8288
  } | undefined;
7480
8289
  authorKinds?: ("agent" | "person" | "mossbear")[] | undefined;
7481
- subjectKinds?: ("item" | "session")[] | undefined;
8290
+ subjectKinds?: ("item" | "artifact" | "session")[] | undefined;
7482
8291
  steeringLabels?: ("correction" | "steering" | "new request" | "acknowledgement" | "insufficient evidence")[] | undefined;
7483
8292
  headSha?: string | undefined;
7484
8293
  branch?: string | undefined;
@@ -7495,7 +8304,7 @@ export declare const SearchRequestSchema: v.SchemaWithPipe<readonly [v.ObjectSch
7495
8304
  [x: string]: string;
7496
8305
  } | undefined;
7497
8306
  authorKinds?: ("agent" | "person" | "mossbear")[] | undefined;
7498
- subjectKinds?: ("item" | "session")[] | undefined;
8307
+ subjectKinds?: ("item" | "artifact" | "session")[] | undefined;
7499
8308
  steeringLabels?: ("correction" | "steering" | "new request" | "acknowledgement" | "insufficient evidence")[] | undefined;
7500
8309
  headSha?: string | undefined;
7501
8310
  branch?: string | undefined;
@@ -7512,7 +8321,7 @@ export declare const SearchRequestSchema: v.SchemaWithPipe<readonly [v.ObjectSch
7512
8321
  [x: string]: string;
7513
8322
  } | undefined;
7514
8323
  authorKinds?: ("agent" | "person" | "mossbear")[] | undefined;
7515
- subjectKinds?: ("item" | "session")[] | undefined;
8324
+ subjectKinds?: ("item" | "artifact" | "session")[] | undefined;
7516
8325
  steeringLabels?: ("correction" | "steering" | "new request" | "acknowledgement" | "insufficient evidence")[] | undefined;
7517
8326
  headSha?: string | undefined;
7518
8327
  branch?: string | undefined;
@@ -7529,7 +8338,7 @@ export declare const SearchRequestSchema: v.SchemaWithPipe<readonly [v.ObjectSch
7529
8338
  [x: string]: string;
7530
8339
  } | undefined;
7531
8340
  authorKinds?: ("agent" | "person" | "mossbear")[] | undefined;
7532
- subjectKinds?: ("item" | "session")[] | undefined;
8341
+ subjectKinds?: ("item" | "artifact" | "session")[] | undefined;
7533
8342
  steeringLabels?: ("correction" | "steering" | "new request" | "acknowledgement" | "insufficient evidence")[] | undefined;
7534
8343
  headSha?: string | undefined;
7535
8344
  branch?: string | undefined;
@@ -7546,7 +8355,7 @@ export declare const SearchRequestSchema: v.SchemaWithPipe<readonly [v.ObjectSch
7546
8355
  [x: string]: string;
7547
8356
  } | undefined;
7548
8357
  authorKinds?: ("agent" | "person" | "mossbear")[] | undefined;
7549
- subjectKinds?: ("item" | "session")[] | undefined;
8358
+ subjectKinds?: ("item" | "artifact" | "session")[] | undefined;
7550
8359
  steeringLabels?: ("correction" | "steering" | "new request" | "acknowledgement" | "insufficient evidence")[] | undefined;
7551
8360
  headSha?: string | undefined;
7552
8361
  branch?: string | undefined;
@@ -7563,7 +8372,7 @@ export declare const SearchRequestSchema: v.SchemaWithPipe<readonly [v.ObjectSch
7563
8372
  [x: string]: string;
7564
8373
  } | undefined;
7565
8374
  authorKinds?: ("agent" | "person" | "mossbear")[] | undefined;
7566
- subjectKinds?: ("item" | "session")[] | undefined;
8375
+ subjectKinds?: ("item" | "artifact" | "session")[] | undefined;
7567
8376
  steeringLabels?: ("correction" | "steering" | "new request" | "acknowledgement" | "insufficient evidence")[] | undefined;
7568
8377
  headSha?: string | undefined;
7569
8378
  branch?: string | undefined;
@@ -7626,7 +8435,7 @@ export declare const SearchVerdictHitSchema: v.ObjectSchema<{
7626
8435
  }, undefined>;
7627
8436
  export type SearchVerdictHit = v.InferOutput<typeof SearchVerdictHitSchema>;
7628
8437
  /**
7629
- * A saved document whose name or body matched — an item `pull_context` returns
8438
+ * A saved document whose name or body matched — an item `pull_bundle` returns
7630
8439
  * as `type: content`. The name, workspace name and excerpt are wrapped in
7631
8440
  * `untrusted`'s markers.
7632
8441
  */
@@ -7639,7 +8448,7 @@ export declare const SearchContentHitSchema: v.ObjectSchema<{
7639
8448
  readonly workspaceName: v.StringSchema<undefined>;
7640
8449
  /**
7641
8450
  * Slugs of the bundles that hold the item and that the caller may read — the
7642
- * argument `pull_context` takes to read the whole document. Never more than
8451
+ * argument `pull_bundle` takes to read the whole document. Never more than
7643
8452
  * a scoped caller's allowlist reaches.
7644
8453
  */
7645
8454
  readonly bundles: v.ArraySchema<v.StringSchema<undefined>, undefined>;
@@ -7708,7 +8517,78 @@ export declare const SearchSessionCommentHitSchema: v.ObjectSchema<{
7708
8517
  readonly url: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
7709
8518
  readonly excerpt: v.StringSchema<undefined>;
7710
8519
  }, undefined>;
8520
+ /**
8521
+ * The same hit under the new name for its subject (one-artifact Stage 3): a
8522
+ * client reads either until every server sends `artifact`.
8523
+ */
8524
+ export declare const SearchArtifactCommentHitSchema: v.ObjectSchema<{
8525
+ readonly subjectKind: v.LiteralSchema<"artifact", undefined>;
8526
+ readonly itemId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
8527
+ /**
8528
+ * The guide the item belongs to, or null for a standalone document. A comment
8529
+ * on a guide sits on its body file, so this is the id the dashboard's guide
8530
+ * page takes; `itemId` is the one a document page takes.
8531
+ */
8532
+ readonly guideId: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, undefined>;
8533
+ /** Wrapped in `untrusted`'s markers; null when the item has no name. */
8534
+ readonly itemName: v.NullableSchema<v.StringSchema<undefined>, undefined>;
8535
+ readonly workspaceId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
8536
+ /** Wrapped in `untrusted`'s markers. */
8537
+ readonly workspaceName: v.StringSchema<undefined>;
8538
+ /** Whether the item has been edited since the comment was written. */
8539
+ readonly itemChangedSince: v.BooleanSchema<undefined>;
8540
+ /**
8541
+ * Whether the match is in the comment's text or in the replacement it
8542
+ * suggests (Mossbear's drafted edits).
8543
+ */
8544
+ readonly matchedIn: v.PicklistSchema<["body", "suggestion"], undefined>;
8545
+ /**
8546
+ * A Mossbear suggestion's draft state: whether its owner has handed it to
8547
+ * their agents. Absent on a person's or an agent's comment and on a reply.
8548
+ */
8549
+ readonly approved: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
8550
+ readonly commentId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
8551
+ readonly threadId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
8552
+ readonly authorKind: v.PicklistSchema<readonly ["person", "agent", "mossbear"], undefined>;
8553
+ readonly resolved: v.BooleanSchema<undefined>;
8554
+ readonly createdAt: v.StringSchema<undefined>;
8555
+ readonly url: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
8556
+ readonly excerpt: v.StringSchema<undefined>;
8557
+ }, undefined>;
7711
8558
  export declare const SearchCommentHitSchema: v.VariantSchema<"subjectKind", [v.ObjectSchema<{
8559
+ readonly subjectKind: v.LiteralSchema<"artifact", undefined>;
8560
+ readonly itemId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
8561
+ /**
8562
+ * The guide the item belongs to, or null for a standalone document. A comment
8563
+ * on a guide sits on its body file, so this is the id the dashboard's guide
8564
+ * page takes; `itemId` is the one a document page takes.
8565
+ */
8566
+ readonly guideId: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, undefined>;
8567
+ /** Wrapped in `untrusted`'s markers; null when the item has no name. */
8568
+ readonly itemName: v.NullableSchema<v.StringSchema<undefined>, undefined>;
8569
+ readonly workspaceId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
8570
+ /** Wrapped in `untrusted`'s markers. */
8571
+ readonly workspaceName: v.StringSchema<undefined>;
8572
+ /** Whether the item has been edited since the comment was written. */
8573
+ readonly itemChangedSince: v.BooleanSchema<undefined>;
8574
+ /**
8575
+ * Whether the match is in the comment's text or in the replacement it
8576
+ * suggests (Mossbear's drafted edits).
8577
+ */
8578
+ readonly matchedIn: v.PicklistSchema<["body", "suggestion"], undefined>;
8579
+ /**
8580
+ * A Mossbear suggestion's draft state: whether its owner has handed it to
8581
+ * their agents. Absent on a person's or an agent's comment and on a reply.
8582
+ */
8583
+ readonly approved: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
8584
+ readonly commentId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
8585
+ readonly threadId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
8586
+ readonly authorKind: v.PicklistSchema<readonly ["person", "agent", "mossbear"], undefined>;
8587
+ readonly resolved: v.BooleanSchema<undefined>;
8588
+ readonly createdAt: v.StringSchema<undefined>;
8589
+ readonly url: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
8590
+ readonly excerpt: v.StringSchema<undefined>;
8591
+ }, undefined>, v.ObjectSchema<{
7712
8592
  readonly subjectKind: v.LiteralSchema<"item", undefined>;
7713
8593
  readonly itemId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
7714
8594
  /**
@@ -7901,7 +8781,7 @@ export declare const SearchContentReportSchema: v.VariantSchema<"status", [v.Obj
7901
8781
  readonly workspaceName: v.StringSchema<undefined>;
7902
8782
  /**
7903
8783
  * Slugs of the bundles that hold the item and that the caller may read — the
7904
- * argument `pull_context` takes to read the whole document. Never more than
8784
+ * argument `pull_bundle` takes to read the whole document. Never more than
7905
8785
  * a scoped caller's allowlist reaches.
7906
8786
  */
7907
8787
  readonly bundles: v.ArraySchema<v.StringSchema<undefined>, undefined>;
@@ -7925,6 +8805,39 @@ export declare const SearchCommentsReportSchema: v.VariantSchema<"status", [v.Ob
7925
8805
  readonly narrowedBy: v.NullableSchema<v.PicklistSchema<["narrowed-by-bundle-allowlist"], undefined>, undefined>;
7926
8806
  /** Newest first, at most the request's limit. */
7927
8807
  readonly hits: v.ArraySchema<v.VariantSchema<"subjectKind", [v.ObjectSchema<{
8808
+ readonly subjectKind: v.LiteralSchema<"artifact", undefined>;
8809
+ readonly itemId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
8810
+ /**
8811
+ * The guide the item belongs to, or null for a standalone document. A comment
8812
+ * on a guide sits on its body file, so this is the id the dashboard's guide
8813
+ * page takes; `itemId` is the one a document page takes.
8814
+ */
8815
+ readonly guideId: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, undefined>;
8816
+ /** Wrapped in `untrusted`'s markers; null when the item has no name. */
8817
+ readonly itemName: v.NullableSchema<v.StringSchema<undefined>, undefined>;
8818
+ readonly workspaceId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
8819
+ /** Wrapped in `untrusted`'s markers. */
8820
+ readonly workspaceName: v.StringSchema<undefined>;
8821
+ /** Whether the item has been edited since the comment was written. */
8822
+ readonly itemChangedSince: v.BooleanSchema<undefined>;
8823
+ /**
8824
+ * Whether the match is in the comment's text or in the replacement it
8825
+ * suggests (Mossbear's drafted edits).
8826
+ */
8827
+ readonly matchedIn: v.PicklistSchema<["body", "suggestion"], undefined>;
8828
+ /**
8829
+ * A Mossbear suggestion's draft state: whether its owner has handed it to
8830
+ * their agents. Absent on a person's or an agent's comment and on a reply.
8831
+ */
8832
+ readonly approved: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
8833
+ readonly commentId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
8834
+ readonly threadId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
8835
+ readonly authorKind: v.PicklistSchema<readonly ["person", "agent", "mossbear"], undefined>;
8836
+ readonly resolved: v.BooleanSchema<undefined>;
8837
+ readonly createdAt: v.StringSchema<undefined>;
8838
+ readonly url: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
8839
+ readonly excerpt: v.StringSchema<undefined>;
8840
+ }, undefined>, v.ObjectSchema<{
7928
8841
  readonly subjectKind: v.LiteralSchema<"item", undefined>;
7929
8842
  readonly itemId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
7930
8843
  /**
@@ -8142,7 +9055,7 @@ export declare const SearchResponseSchema: v.ObjectSchema<{
8142
9055
  readonly workspaceName: v.StringSchema<undefined>;
8143
9056
  /**
8144
9057
  * Slugs of the bundles that hold the item and that the caller may read — the
8145
- * argument `pull_context` takes to read the whole document. Never more than
9058
+ * argument `pull_bundle` takes to read the whole document. Never more than
8146
9059
  * a scoped caller's allowlist reaches.
8147
9060
  */
8148
9061
  readonly bundles: v.ArraySchema<v.StringSchema<undefined>, undefined>;
@@ -8167,6 +9080,39 @@ export declare const SearchResponseSchema: v.ObjectSchema<{
8167
9080
  readonly narrowedBy: v.NullableSchema<v.PicklistSchema<["narrowed-by-bundle-allowlist"], undefined>, undefined>;
8168
9081
  /** Newest first, at most the request's limit. */
8169
9082
  readonly hits: v.ArraySchema<v.VariantSchema<"subjectKind", [v.ObjectSchema<{
9083
+ readonly subjectKind: v.LiteralSchema<"artifact", undefined>;
9084
+ readonly itemId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
9085
+ /**
9086
+ * The guide the item belongs to, or null for a standalone document. A comment
9087
+ * on a guide sits on its body file, so this is the id the dashboard's guide
9088
+ * page takes; `itemId` is the one a document page takes.
9089
+ */
9090
+ readonly guideId: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, undefined>;
9091
+ /** Wrapped in `untrusted`'s markers; null when the item has no name. */
9092
+ readonly itemName: v.NullableSchema<v.StringSchema<undefined>, undefined>;
9093
+ readonly workspaceId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
9094
+ /** Wrapped in `untrusted`'s markers. */
9095
+ readonly workspaceName: v.StringSchema<undefined>;
9096
+ /** Whether the item has been edited since the comment was written. */
9097
+ readonly itemChangedSince: v.BooleanSchema<undefined>;
9098
+ /**
9099
+ * Whether the match is in the comment's text or in the replacement it
9100
+ * suggests (Mossbear's drafted edits).
9101
+ */
9102
+ readonly matchedIn: v.PicklistSchema<["body", "suggestion"], undefined>;
9103
+ /**
9104
+ * A Mossbear suggestion's draft state: whether its owner has handed it to
9105
+ * their agents. Absent on a person's or an agent's comment and on a reply.
9106
+ */
9107
+ readonly approved: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
9108
+ readonly commentId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
9109
+ readonly threadId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
9110
+ readonly authorKind: v.PicklistSchema<readonly ["person", "agent", "mossbear"], undefined>;
9111
+ readonly resolved: v.BooleanSchema<undefined>;
9112
+ readonly createdAt: v.StringSchema<undefined>;
9113
+ readonly url: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
9114
+ readonly excerpt: v.StringSchema<undefined>;
9115
+ }, undefined>, v.ObjectSchema<{
8170
9116
  readonly subjectKind: v.LiteralSchema<"item", undefined>;
8171
9117
  readonly itemId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
8172
9118
  /**
@@ -8475,9 +9421,9 @@ export declare function parseDeleteBundleResponse(data: unknown): {
8475
9421
  deleted: boolean;
8476
9422
  };
8477
9423
  export declare function parseContextItem(data: unknown): {
9424
+ type: string;
8478
9425
  id: string;
8479
9426
  artifactId?: string | null | undefined;
8480
- type: string;
8481
9427
  name: string;
8482
9428
  role: string | null;
8483
9429
  format: string | null;
@@ -8531,9 +9477,9 @@ export declare function parseContextItem(data: unknown): {
8531
9477
  };
8532
9478
  export declare function parseContextItemsResponse(data: unknown): {
8533
9479
  items: {
9480
+ type: string;
8534
9481
  id: string;
8535
9482
  artifactId?: string | null | undefined;
8536
- type: string;
8537
9483
  name: string;
8538
9484
  role: string | null;
8539
9485
  format: string | null;
@@ -8609,9 +9555,9 @@ export declare function parsePushContextRequest(data: unknown): {
8609
9555
  };
8610
9556
  export declare function parsePushContextResponse(data: unknown): {
8611
9557
  item: {
9558
+ type: string;
8612
9559
  id: string;
8613
9560
  artifactId?: string | null | undefined;
8614
- type: string;
8615
9561
  name: string;
8616
9562
  role: string | null;
8617
9563
  format: string | null;
@@ -8682,9 +9628,9 @@ export declare function parseUpdateContextItemRequest(data: unknown): {
8682
9628
  };
8683
9629
  export declare function parseUpdateContextItemResponse(data: unknown): {
8684
9630
  item: {
9631
+ type: string;
8685
9632
  id: string;
8686
9633
  artifactId?: string | null | undefined;
8687
- type: string;
8688
9634
  name: string;
8689
9635
  role: string | null;
8690
9636
  format: string | null;
@@ -8754,9 +9700,9 @@ export declare function parseUpdateContextItemBody(data: unknown): {
8754
9700
  };
8755
9701
  export declare function parseContextItemResponse(data: unknown): {
8756
9702
  item: {
9703
+ type: string;
8757
9704
  id: string;
8758
9705
  artifactId?: string | null | undefined;
8759
- type: string;
8760
9706
  name: string;
8761
9707
  role: string | null;
8762
9708
  format: string | null;
@@ -8812,9 +9758,9 @@ export declare function parseContextItemResponse(data: unknown): {
8812
9758
  export declare function parseArchiveContextItemResponse(data: unknown): {
8813
9759
  archived: boolean;
8814
9760
  item: {
9761
+ type: string;
8815
9762
  id: string;
8816
9763
  artifactId?: string | null | undefined;
8817
- type: string;
8818
9764
  name: string;
8819
9765
  role: string | null;
8820
9766
  format: string | null;
@@ -9187,7 +10133,7 @@ export declare function parseAgentCommentResponse(data: unknown): {
9187
10133
  id: string;
9188
10134
  threadId: string;
9189
10135
  subject: {
9190
- kind: "item" | "session";
10136
+ kind: "item" | "artifact" | "session";
9191
10137
  id: string;
9192
10138
  };
9193
10139
  body: string;
@@ -9440,6 +10386,23 @@ export declare function parseSearchResponse(data: unknown): {
9440
10386
  createdAt: string;
9441
10387
  url?: string | undefined;
9442
10388
  excerpt: string;
10389
+ } | {
10390
+ subjectKind: "artifact";
10391
+ itemId: string;
10392
+ guideId: string | null;
10393
+ itemName: string | null;
10394
+ workspaceId: string;
10395
+ workspaceName: string;
10396
+ itemChangedSince: boolean;
10397
+ matchedIn: "suggestion" | "body";
10398
+ approved?: boolean | undefined;
10399
+ commentId: string;
10400
+ threadId: string;
10401
+ authorKind: "agent" | "person" | "mossbear";
10402
+ resolved: boolean;
10403
+ createdAt: string;
10404
+ url?: string | undefined;
10405
+ excerpt: string;
9443
10406
  } | {
9444
10407
  subjectKind: "session";
9445
10408
  sessionId: string;