@mossbear/protocol 0.1.0-alpha.52 → 0.1.0-alpha.54

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
@@ -831,8 +831,17 @@ export declare const DeleteBundleResponseSchema: v.ObjectSchema<{
831
831
  readonly deleted: v.BooleanSchema<undefined>;
832
832
  }, undefined>;
833
833
  export declare const ContextItemTypeSchema: v.PicklistSchema<string[], undefined>;
834
- export declare const PushContentTypeSchema: v.PicklistSchema<("document" | "reference" | "asset")[], undefined>;
835
- export declare const InboxContentTypeSchema: v.PicklistSchema<("document" | "reference" | "asset")[], undefined>;
834
+ /**
835
+ * What a `?types=` filter parses.
836
+ *
837
+ * Equal to {@link ContextItemTypeSchema}'s values again: it was briefly wider
838
+ * so a filter written against the pre-rename vocabulary returned the kind
839
+ * those rows became rather than an empty page, and that window closed with
840
+ * the release that moved the CLI's own vocabulary onto `content`.
841
+ */
842
+ export declare const ContextItemTypeFilterSchema: v.PicklistSchema<string[], undefined>;
843
+ export declare const PushContentTypeSchema: v.PicklistSchema<("content" | "asset")[], undefined>;
844
+ export declare const InboxContentTypeSchema: v.PicklistSchema<("content" | "asset")[], undefined>;
836
845
  /** Max serialized size (UTF-8 bytes) of a pushed or captured item's content. */
837
846
  export declare const MAX_CONTEXT_CONTENT_BYTES: number;
838
847
  /**
@@ -852,11 +861,159 @@ export declare const GuideAliasSchema: v.ObjectSchema<{
852
861
  readonly path: 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">]>;
853
862
  }, undefined>;
854
863
  export type GuideAlias = v.InferOutput<typeof GuideAliasSchema>;
864
+ /**
865
+ * The markers every untrusted block in a response is wrapped in, plus a
866
+ * statement of what they mean.
867
+ *
868
+ * Generated per response from the content itself, so no marker-like text
869
+ * inside a block can end it early — a property `deriveDelimiterToken` checks
870
+ * rather than assumes.
871
+ *
872
+ * Named for the guide-history response it was written for and shared by every
873
+ * payload that places somebody else's words in front of an agent: a grade's
874
+ * reasoning, and now an item's notes. One marker scheme, not one per payload —
875
+ * a second scheme is a second thing a reader has to be taught to respect.
876
+ * Declared here, above its first user, rather than beside that response.
877
+ */
878
+ export declare const GuideHistoryUntrustedSchema: v.ObjectSchema<{
879
+ readonly token: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
880
+ readonly startMarker: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
881
+ readonly endMarker: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
882
+ readonly note: v.StringSchema<undefined>;
883
+ }, undefined>;
884
+ export type GuideHistoryUntrusted = v.InferOutput<typeof GuideHistoryUntrustedSchema>;
885
+ /**
886
+ * How many open notes one item carries on the wire, newest first.
887
+ *
888
+ * A wire bound, not a product limit: the write side refuses the note that
889
+ * would exceed it *by name* (see the dashboard's note mutator), so this cap is
890
+ * never the thing that silently drops a request a person left.
891
+ */
892
+ export declare const MAX_ITEM_NOTES_ON_WIRE = 20;
893
+ /**
894
+ * One note a **person** left about a context item, riding the item it is about.
895
+ *
896
+ * A note is not an item: it is not a member, not projected, not versioned and
897
+ * not capturable. It travels on the item so that it inherits every delivery
898
+ * decision the item already went through — workspace scope, the archived drop,
899
+ * the response limit, the subscriber's mute — rather than restating them.
900
+ *
901
+ * **Every `body` here is already wrapped in the response's untrusted markers**
902
+ * (`ContextItemsResponseSchema.untrusted`). A reader emits the bytes as it
903
+ * received them and never re-wraps them: the markers are derived against the
904
+ * bodies the server sent, so a second wrapping cannot claim the same guarantee.
905
+ */
906
+ export declare const ContextItemNoteSchema: v.ObjectSchema<{
907
+ readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
908
+ /** The note's text, already wrapped in the response's untrusted markers. */
909
+ readonly body: v.StringSchema<undefined>;
910
+ /** The author's display name as the workspace shows it, or null. Never an email. */
911
+ readonly authorName: v.NullableSchema<v.StringSchema<undefined>, undefined>;
912
+ /** ISO timestamp, machine format. */
913
+ readonly createdAt: v.StringSchema<undefined>;
914
+ /** The item's content version the note was written against. */
915
+ readonly itemVersion: v.NumberSchema<undefined>;
916
+ /** True when the item's current version is greater than `itemVersion`. */
917
+ readonly itemChangedSince: v.BooleanSchema<undefined>;
918
+ /**
919
+ * How many agent reads were handed this note **before** this one — so a
920
+ * note reaching an agent for the first time reports `0`.
921
+ *
922
+ * It is the stored count as it read at the moment the response was built;
923
+ * the serve this response *is* has not been counted yet. Excluded rather
924
+ * than included because the count is recorded best-effort: a response that
925
+ * claimed to include itself would be wrong whenever that record failed, and
926
+ * a number that is sometimes off by one is worse than one that is
927
+ * consistently the prior total.
928
+ *
929
+ * So `deliveredCount > 0` means an earlier read was handed this note, and
930
+ * `0` means this read is the first. Neither says a model took it in — only
931
+ * that the server handed it over.
932
+ */
933
+ readonly deliveredCount: v.NumberSchema<undefined>;
934
+ /**
935
+ * This note's thread root — its own id for every note written today, since
936
+ * no reply exists yet. Ignorable now; load-bearing once a reply is a second
937
+ * row with a different id here. It is on the wire from the first response
938
+ * because the wire contract is consumed by installed CLI versions: reshaping
939
+ * a flat `notes` array into threads-of-notes later would be a breaking
940
+ * change, while a field today's readers ignore costs them nothing.
941
+ */
942
+ readonly threadId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
943
+ /**
944
+ * Always `null` today — no reply exists to point at. Present now so an older
945
+ * reader meeting a future response that carries real replies degrades to
946
+ * "a flat list of notes" rather than failing to parse.
947
+ */
948
+ readonly replyToId: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, undefined>;
949
+ }, undefined>;
950
+ export type ContextItemNote = v.InferOutput<typeof ContextItemNoteSchema>;
951
+ /**
952
+ * The revision published bytes were read from — 40 hex characters for a sha1
953
+ * repository, 64 for a sha256 one. Lowercase only, because that is what
954
+ * `git rev-parse` emits and accepting both spellings would make two rows naming
955
+ * one commit compare unequal.
956
+ *
957
+ * Deliberately not an abbreviation: a short sha is ambiguous by construction and
958
+ * this is the field a subscriber uses to answer "what did I get".
959
+ */
960
+ export declare const CommitShaSchema: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "commitSha must be 40 or 64 lowercase hex characters">]>;
961
+ /**
962
+ * Where a **git-owned** artifact comes from (`artifact-ownership-and-delivery-plan.md`
963
+ * → slice 1). Its presence is what says git owns the artifact: the working copy
964
+ * and the commit are the authority, and Mossbear distributes the committed
965
+ * revision rather than a second independently editable copy.
966
+ *
967
+ * **One object rather than three sibling keys on the item**, because the legal
968
+ * states are "all of it" or "none of it" and a nested object makes the absent
969
+ * state a single missing key instead of three that a writer could half-fill.
970
+ * The two fields here are the two that cannot be half-filled: `branch` is the
971
+ * one optional member, so an object with a repo and a revision is always a
972
+ * complete source.
973
+ *
974
+ * **The source path is not here.** The item's own `path` is the repo-relative
975
+ * path, and it is a required member of the subset — but the requirement is held
976
+ * by the database, not restated here; see `gitSource` on `ContextItemSchema`
977
+ * below for why a wire rule that looked identical would not be. What matters at
978
+ * this layer is that there is only ever one path, never a source path beside a
979
+ * projection path that publication and delivery could disagree about.
980
+ */
981
+ export declare const GitSourceSchema: v.ObjectSchema<{
982
+ /**
983
+ * The committed `project.id` of the source repository — the same id space as
984
+ * an item's delivery-scoping `projectId` below, but a different fact: that one
985
+ * says which repo an item is materialized into and is stamped onto
986
+ * Mossbear-owned rows too, this one says who may edit it.
987
+ */
988
+ 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">]>;
989
+ readonly commitSha: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "commitSha must be 40 or 64 lowercase hex characters">]>;
990
+ /**
991
+ * The branch the publishing commit was on. **The one optional member**:
992
+ * publication is not restricted by branch, so this is recorded so a subscriber
993
+ * can see what they got, and a detached HEAD has none to record.
994
+ */
995
+ readonly branch: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 255, undefined>]>, undefined>;
996
+ }, undefined>;
855
997
  export declare const ContextItemSchema: v.ObjectSchema<{
856
998
  readonly id: v.StringSchema<undefined>;
857
999
  readonly type: v.PicklistSchema<string[], undefined>;
858
1000
  readonly name: v.StringSchema<undefined>;
859
- readonly contentType: v.StringSchema<undefined>;
1001
+ /**
1002
+ * The stored `(role, format)` pair, as two bare nullable strings.
1003
+ *
1004
+ * **Both are deliberately unenumerated.** A client switches on one value it
1005
+ * cares about — `role === 'criteria'` is how a rubric is told from ordinary
1006
+ * prose, which `type` cannot say because a rubric serializes as a `document` —
1007
+ * and a server that adds a fourth role or a fifth format must not break a
1008
+ * client that has never heard of it. Narrowing them here would make every such
1009
+ * addition a breaking wire change for no reader's benefit.
1010
+ *
1011
+ * Null on exactly the rows that carry no content: a tombstone, and an alias.
1012
+ * A `guide` item has no pair at all — it is a different table — and reports
1013
+ * both as null.
1014
+ */
1015
+ readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
1016
+ readonly format: v.NullableSchema<v.StringSchema<undefined>, undefined>;
860
1017
  readonly content: v.NullableSchema<v.StringSchema<undefined>, undefined>;
861
1018
  readonly origin: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
862
1019
  readonly version: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
@@ -884,14 +1041,161 @@ export declare const ContextItemSchema: v.ObjectSchema<{
884
1041
  root: "project" | "global";
885
1042
  path: string;
886
1043
  }[], 8, undefined>]>, undefined>;
1044
+ /**
1045
+ * Open notes a person left about this item, newest first.
1046
+ *
1047
+ * Optional, and absent rather than empty when there are none — the same rule
1048
+ * `aliases` and `projectId` follow above, and for the same reason: an older
1049
+ * reader against a newer server ignores the key, and a newer reader against
1050
+ * an older server reads "no notes" instead of failing.
1051
+ *
1052
+ * **Absence is not a verdict.** No notes here means none were served on this
1053
+ * item in this response — not that nobody has anything to say about it.
1054
+ */
1055
+ readonly notes: v.OptionalSchema<v.SchemaWithPipe<readonly [v.ArraySchema<v.ObjectSchema<{
1056
+ readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
1057
+ /** The note's text, already wrapped in the response's untrusted markers. */
1058
+ readonly body: v.StringSchema<undefined>;
1059
+ /** The author's display name as the workspace shows it, or null. Never an email. */
1060
+ readonly authorName: v.NullableSchema<v.StringSchema<undefined>, undefined>;
1061
+ /** ISO timestamp, machine format. */
1062
+ readonly createdAt: v.StringSchema<undefined>;
1063
+ /** The item's content version the note was written against. */
1064
+ readonly itemVersion: v.NumberSchema<undefined>;
1065
+ /** True when the item's current version is greater than `itemVersion`. */
1066
+ readonly itemChangedSince: v.BooleanSchema<undefined>;
1067
+ /**
1068
+ * How many agent reads were handed this note **before** this one — so a
1069
+ * note reaching an agent for the first time reports `0`.
1070
+ *
1071
+ * It is the stored count as it read at the moment the response was built;
1072
+ * the serve this response *is* has not been counted yet. Excluded rather
1073
+ * than included because the count is recorded best-effort: a response that
1074
+ * claimed to include itself would be wrong whenever that record failed, and
1075
+ * a number that is sometimes off by one is worse than one that is
1076
+ * consistently the prior total.
1077
+ *
1078
+ * So `deliveredCount > 0` means an earlier read was handed this note, and
1079
+ * `0` means this read is the first. Neither says a model took it in — only
1080
+ * that the server handed it over.
1081
+ */
1082
+ readonly deliveredCount: v.NumberSchema<undefined>;
1083
+ /**
1084
+ * This note's thread root — its own id for every note written today, since
1085
+ * no reply exists yet. Ignorable now; load-bearing once a reply is a second
1086
+ * row with a different id here. It is on the wire from the first response
1087
+ * because the wire contract is consumed by installed CLI versions: reshaping
1088
+ * a flat `notes` array into threads-of-notes later would be a breaking
1089
+ * change, while a field today's readers ignore costs them nothing.
1090
+ */
1091
+ readonly threadId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
1092
+ /**
1093
+ * Always `null` today — no reply exists to point at. Present now so an older
1094
+ * reader meeting a future response that carries real replies degrades to
1095
+ * "a flat list of notes" rather than failing to parse.
1096
+ */
1097
+ readonly replyToId: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, undefined>;
1098
+ }, undefined>, undefined>, v.MaxLengthAction<{
1099
+ id: string;
1100
+ body: string;
1101
+ authorName: string | null;
1102
+ createdAt: string;
1103
+ itemVersion: number;
1104
+ itemChangedSince: boolean;
1105
+ deliveredCount: number;
1106
+ threadId: string;
1107
+ replyToId: string | null;
1108
+ }[], 20, undefined>]>, undefined>;
887
1109
  readonly updatedAt: v.StringSchema<undefined>;
1110
+ /**
1111
+ * Present iff this artifact is owned by git. Absent means Mossbear owns it
1112
+ * and it is editable in the dashboard.
1113
+ *
1114
+ * **Optional, and absence is not yet a verdict.** Nothing writes this before
1115
+ * `publish` ships, so today every item omits it, and the existing bundle-home
1116
+ * rule — a bundle may name one repo as its only writer, and the server
1117
+ * refuses every other writer by name — is what still protects items a repo
1118
+ * already owns. A reader must not treat an absent `gitSource` as permission
1119
+ * to publish back.
1120
+ *
1121
+ * **Optional *and* nullable, like every other late-added column on this item.**
1122
+ * A serializer that maps the columns straight through emits `null` for a
1123
+ * Mossbear-owned row, and a key that only accepted `undefined` would throw on
1124
+ * the whole response rather than on the one item — `parseContextItemsResponse`
1125
+ * parses a pull as a batch. Both spellings read the same way: no git source.
1126
+ *
1127
+ * **`path` is the third required member of the subset and is not re-checked
1128
+ * here.** The database holds that invariant
1129
+ * (`guide_files_git_source_subset`), and a wire rule that looked identical
1130
+ * would in fact be stricter: `path` is serialized through a scope helper that
1131
+ * emits `null` for a path this schema cannot parse, so a single such row would
1132
+ * fail every other item in the same pull. A git-owned item that arrives
1133
+ * without a usable path is a broken item, not a broken response.
1134
+ */
1135
+ readonly gitSource: v.OptionalSchema<v.NullableSchema<v.ObjectSchema<{
1136
+ /**
1137
+ * The committed `project.id` of the source repository — the same id space as
1138
+ * an item's delivery-scoping `projectId` below, but a different fact: that one
1139
+ * says which repo an item is materialized into and is stamped onto
1140
+ * Mossbear-owned rows too, this one says who may edit it.
1141
+ */
1142
+ 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">]>;
1143
+ readonly commitSha: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "commitSha must be 40 or 64 lowercase hex characters">]>;
1144
+ /**
1145
+ * The branch the publishing commit was on. **The one optional member**:
1146
+ * publication is not restricted by branch, so this is recorded so a subscriber
1147
+ * can see what they got, and a detached HEAD has none to record.
1148
+ */
1149
+ readonly branch: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 255, undefined>]>, undefined>;
1150
+ }, undefined>, undefined>, undefined>;
1151
+ /**
1152
+ * This artifact is a **tombstone**: the repository that publishes it deleted
1153
+ * the file, so what the item still carries is the last revision rather than a
1154
+ * current one (`artifact-ownership-and-delivery-plan.md` → D28).
1155
+ *
1156
+ * **It is still delivered, and that is deliberate.** Dropping the item from
1157
+ * the response would say the same thing more quietly and cost two things
1158
+ * worth more than the byte: the publishing repo would lose the id it needs to
1159
+ * republish the path in place — re-adding a deleted file would create a
1160
+ * second artifact at the same path rather than a new revision of the one
1161
+ * that is there — and a reader would be left unable to tell a removal from
1162
+ * a bundle it has stopped being able to see. What the flag asks of a client
1163
+ * is one thing: do not materialize it. A file left at a discovery root keeps
1164
+ * feeding deleted guidance into every agent that reads that repo, which is
1165
+ * the failure the decision exists to stop.
1166
+ *
1167
+ * **Optional, and absent means an ordinary artifact.** A client that has
1168
+ * never heard of it behaves as it always did — it keeps the last published
1169
+ * revision on disk, which is the retain behaviour this replaces rather than a
1170
+ * new failure. That is what makes the server safe to ship first.
1171
+ *
1172
+ * `literal(true)` rather than a boolean: `removed: false` would be a second
1173
+ * spelling of absence, and an artifact that came back is content again rather
1174
+ * than a tombstone that says no.
1175
+ */
1176
+ readonly removed: v.OptionalSchema<v.LiteralSchema<true, undefined>, undefined>;
888
1177
  }, undefined>;
889
1178
  export declare const ContextItemsResponseSchema: v.ObjectSchema<{
890
1179
  readonly items: v.ArraySchema<v.ObjectSchema<{
891
1180
  readonly id: v.StringSchema<undefined>;
892
1181
  readonly type: v.PicklistSchema<string[], undefined>;
893
1182
  readonly name: v.StringSchema<undefined>;
894
- readonly contentType: v.StringSchema<undefined>;
1183
+ /**
1184
+ * The stored `(role, format)` pair, as two bare nullable strings.
1185
+ *
1186
+ * **Both are deliberately unenumerated.** A client switches on one value it
1187
+ * cares about — `role === 'criteria'` is how a rubric is told from ordinary
1188
+ * prose, which `type` cannot say because a rubric serializes as a `document` —
1189
+ * and a server that adds a fourth role or a fifth format must not break a
1190
+ * client that has never heard of it. Narrowing them here would make every such
1191
+ * addition a breaking wire change for no reader's benefit.
1192
+ *
1193
+ * Null on exactly the rows that carry no content: a tombstone, and an alias.
1194
+ * A `guide` item has no pair at all — it is a different table — and reports
1195
+ * both as null.
1196
+ */
1197
+ readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
1198
+ readonly format: v.NullableSchema<v.StringSchema<undefined>, undefined>;
895
1199
  readonly content: v.NullableSchema<v.StringSchema<undefined>, undefined>;
896
1200
  readonly origin: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
897
1201
  readonly version: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
@@ -919,9 +1223,359 @@ export declare const ContextItemsResponseSchema: v.ObjectSchema<{
919
1223
  root: "project" | "global";
920
1224
  path: string;
921
1225
  }[], 8, undefined>]>, undefined>;
1226
+ /**
1227
+ * Open notes a person left about this item, newest first.
1228
+ *
1229
+ * Optional, and absent rather than empty when there are none — the same rule
1230
+ * `aliases` and `projectId` follow above, and for the same reason: an older
1231
+ * reader against a newer server ignores the key, and a newer reader against
1232
+ * an older server reads "no notes" instead of failing.
1233
+ *
1234
+ * **Absence is not a verdict.** No notes here means none were served on this
1235
+ * item in this response — not that nobody has anything to say about it.
1236
+ */
1237
+ readonly notes: v.OptionalSchema<v.SchemaWithPipe<readonly [v.ArraySchema<v.ObjectSchema<{
1238
+ readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
1239
+ /** The note's text, already wrapped in the response's untrusted markers. */
1240
+ readonly body: v.StringSchema<undefined>;
1241
+ /** The author's display name as the workspace shows it, or null. Never an email. */
1242
+ readonly authorName: v.NullableSchema<v.StringSchema<undefined>, undefined>;
1243
+ /** ISO timestamp, machine format. */
1244
+ readonly createdAt: v.StringSchema<undefined>;
1245
+ /** The item's content version the note was written against. */
1246
+ readonly itemVersion: v.NumberSchema<undefined>;
1247
+ /** True when the item's current version is greater than `itemVersion`. */
1248
+ readonly itemChangedSince: v.BooleanSchema<undefined>;
1249
+ /**
1250
+ * How many agent reads were handed this note **before** this one — so a
1251
+ * note reaching an agent for the first time reports `0`.
1252
+ *
1253
+ * It is the stored count as it read at the moment the response was built;
1254
+ * the serve this response *is* has not been counted yet. Excluded rather
1255
+ * than included because the count is recorded best-effort: a response that
1256
+ * claimed to include itself would be wrong whenever that record failed, and
1257
+ * a number that is sometimes off by one is worse than one that is
1258
+ * consistently the prior total.
1259
+ *
1260
+ * So `deliveredCount > 0` means an earlier read was handed this note, and
1261
+ * `0` means this read is the first. Neither says a model took it in — only
1262
+ * that the server handed it over.
1263
+ */
1264
+ readonly deliveredCount: v.NumberSchema<undefined>;
1265
+ /**
1266
+ * This note's thread root — its own id for every note written today, since
1267
+ * no reply exists yet. Ignorable now; load-bearing once a reply is a second
1268
+ * row with a different id here. It is on the wire from the first response
1269
+ * because the wire contract is consumed by installed CLI versions: reshaping
1270
+ * a flat `notes` array into threads-of-notes later would be a breaking
1271
+ * change, while a field today's readers ignore costs them nothing.
1272
+ */
1273
+ readonly threadId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
1274
+ /**
1275
+ * Always `null` today — no reply exists to point at. Present now so an older
1276
+ * reader meeting a future response that carries real replies degrades to
1277
+ * "a flat list of notes" rather than failing to parse.
1278
+ */
1279
+ readonly replyToId: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, undefined>;
1280
+ }, undefined>, undefined>, v.MaxLengthAction<{
1281
+ id: string;
1282
+ body: string;
1283
+ authorName: string | null;
1284
+ createdAt: string;
1285
+ itemVersion: number;
1286
+ itemChangedSince: boolean;
1287
+ deliveredCount: number;
1288
+ threadId: string;
1289
+ replyToId: string | null;
1290
+ }[], 20, undefined>]>, undefined>;
922
1291
  readonly updatedAt: v.StringSchema<undefined>;
1292
+ /**
1293
+ * Present iff this artifact is owned by git. Absent means Mossbear owns it
1294
+ * and it is editable in the dashboard.
1295
+ *
1296
+ * **Optional, and absence is not yet a verdict.** Nothing writes this before
1297
+ * `publish` ships, so today every item omits it, and the existing bundle-home
1298
+ * rule — a bundle may name one repo as its only writer, and the server
1299
+ * refuses every other writer by name — is what still protects items a repo
1300
+ * already owns. A reader must not treat an absent `gitSource` as permission
1301
+ * to publish back.
1302
+ *
1303
+ * **Optional *and* nullable, like every other late-added column on this item.**
1304
+ * A serializer that maps the columns straight through emits `null` for a
1305
+ * Mossbear-owned row, and a key that only accepted `undefined` would throw on
1306
+ * the whole response rather than on the one item — `parseContextItemsResponse`
1307
+ * parses a pull as a batch. Both spellings read the same way: no git source.
1308
+ *
1309
+ * **`path` is the third required member of the subset and is not re-checked
1310
+ * here.** The database holds that invariant
1311
+ * (`guide_files_git_source_subset`), and a wire rule that looked identical
1312
+ * would in fact be stricter: `path` is serialized through a scope helper that
1313
+ * emits `null` for a path this schema cannot parse, so a single such row would
1314
+ * fail every other item in the same pull. A git-owned item that arrives
1315
+ * without a usable path is a broken item, not a broken response.
1316
+ */
1317
+ readonly gitSource: v.OptionalSchema<v.NullableSchema<v.ObjectSchema<{
1318
+ /**
1319
+ * The committed `project.id` of the source repository — the same id space as
1320
+ * an item's delivery-scoping `projectId` below, but a different fact: that one
1321
+ * says which repo an item is materialized into and is stamped onto
1322
+ * Mossbear-owned rows too, this one says who may edit it.
1323
+ */
1324
+ 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">]>;
1325
+ readonly commitSha: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "commitSha must be 40 or 64 lowercase hex characters">]>;
1326
+ /**
1327
+ * The branch the publishing commit was on. **The one optional member**:
1328
+ * publication is not restricted by branch, so this is recorded so a subscriber
1329
+ * can see what they got, and a detached HEAD has none to record.
1330
+ */
1331
+ readonly branch: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 255, undefined>]>, undefined>;
1332
+ }, undefined>, undefined>, undefined>;
1333
+ /**
1334
+ * This artifact is a **tombstone**: the repository that publishes it deleted
1335
+ * the file, so what the item still carries is the last revision rather than a
1336
+ * current one (`artifact-ownership-and-delivery-plan.md` → D28).
1337
+ *
1338
+ * **It is still delivered, and that is deliberate.** Dropping the item from
1339
+ * the response would say the same thing more quietly and cost two things
1340
+ * worth more than the byte: the publishing repo would lose the id it needs to
1341
+ * republish the path in place — re-adding a deleted file would create a
1342
+ * second artifact at the same path rather than a new revision of the one
1343
+ * that is there — and a reader would be left unable to tell a removal from
1344
+ * a bundle it has stopped being able to see. What the flag asks of a client
1345
+ * is one thing: do not materialize it. A file left at a discovery root keeps
1346
+ * feeding deleted guidance into every agent that reads that repo, which is
1347
+ * the failure the decision exists to stop.
1348
+ *
1349
+ * **Optional, and absent means an ordinary artifact.** A client that has
1350
+ * never heard of it behaves as it always did — it keeps the last published
1351
+ * revision on disk, which is the retain behaviour this replaces rather than a
1352
+ * new failure. That is what makes the server safe to ship first.
1353
+ *
1354
+ * `literal(true)` rather than a boolean: `removed: false` would be a second
1355
+ * spelling of absence, and an artifact that came back is content again rather
1356
+ * than a tombstone that says no.
1357
+ */
1358
+ readonly removed: v.OptionalSchema<v.LiteralSchema<true, undefined>, undefined>;
923
1359
  }, undefined>, undefined>;
1360
+ /**
1361
+ * The markers every note `body` in this response is wrapped in, plus a
1362
+ * statement of what they mean. Present exactly when at least one item
1363
+ * carries a note — there is nothing to delimit otherwise.
1364
+ */
1365
+ readonly untrusted: v.OptionalSchema<v.NullableSchema<v.ObjectSchema<{
1366
+ readonly token: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
1367
+ readonly startMarker: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
1368
+ readonly endMarker: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
1369
+ readonly note: v.StringSchema<undefined>;
1370
+ }, undefined>, undefined>, undefined>;
1371
+ }, undefined>;
1372
+ /**
1373
+ * How many bundles one notes read may name.
1374
+ *
1375
+ * A repo's delivery set is the union of its committed subscriptions and the
1376
+ * reader's account ones, so this bounds a request, not a product limit: a
1377
+ * reader subscribing to more bundles than this asks in two calls rather than
1378
+ * losing the tail silently.
1379
+ */
1380
+ export declare const MAX_NOTE_BUNDLE_IDS = 100;
1381
+ /**
1382
+ * How many times one subscriber is told, in one repo, that a given note is
1383
+ * waiting before the hook falls silent about it.
1384
+ *
1385
+ * **A cap on the interruption, never on the note.** After it is reached the
1386
+ * note is still open, still on the item page, and still returned in full by
1387
+ * the on-demand read — it simply stops being announced in front of the first
1388
+ * turn of every session. So silence here means "nothing new to interrupt you
1389
+ * about", never "nobody left anything".
1390
+ *
1391
+ * Three rather than one, for the reason the announcement exists: the first
1392
+ * session in a repo is often doing unrelated work, so a one-shot announcement
1393
+ * would routinely spend itself on the session least likely to act. Three is a
1394
+ * judgement, named so replacing it is one edit — the same discipline the live
1395
+ * session window is held to.
1396
+ */
1397
+ export declare const MAX_NOTE_ANNOUNCEMENTS_PER_REPO = 3;
1398
+ /**
1399
+ * Ask which notes are waiting for this reader in this repo, and be counted as
1400
+ * told.
1401
+ *
1402
+ * **A write, because being told is a fact the server has to keep.** The count
1403
+ * cannot be `item_notes.delivered_count` — that is one global number across
1404
+ * every subscriber and every repo, so one reader's fill of a note would
1405
+ * silence it for everyone — and it cannot live in the checkout, because the
1406
+ * disposable environments this exists for rebuild the clone every session and
1407
+ * a counter there resets with it, announcing every unresolved note as new
1408
+ * forever.
1409
+ */
1410
+ export declare const AnnounceItemNotesRequestSchema: v.ObjectSchema<{
1411
+ /**
1412
+ * The repo, as its committed config declares it. Required: it is the scope
1413
+ * the count is kept under, and a request with nothing to key on could only
1414
+ * be answered by an uncapped announcement — which is the repeating broadcast
1415
+ * this route exists to end.
1416
+ */
1417
+ 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">]>;
1418
+ /**
1419
+ * The bundles this repo receives — the union the caller already resolved.
1420
+ *
1421
+ * Sent rather than derived, because only half of it is the server's to know:
1422
+ * a repo-scoped subscription lives in the committed config and travels by
1423
+ * `git clone`. Declaring a bundle grants nothing: every one of them is still
1424
+ * filtered by the caller's own workspace membership.
1425
+ */
1426
+ readonly bundleIds: v.SchemaWithPipe<readonly [v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, undefined>, v.MaxLengthAction<string[], 100, undefined>]>;
1427
+ }, undefined>;
1428
+ export type AnnounceItemNotesRequest = v.InferOutput<typeof AnnounceItemNotesRequestSchema>;
1429
+ /**
1430
+ * What an announcement answers: how many notes are waiting, and how many of
1431
+ * them this call was counted as announcing.
1432
+ *
1433
+ * **Two numbers because they answer two questions and a reader needs both.**
1434
+ * `open` is the true state of this repo's notes and is what a caller shows a
1435
+ * person — a number that is sometimes a subset of the truth would be worse
1436
+ * than the silence it replaced. `announced` is how many of those were still
1437
+ * under the cap, and it is the one that decides whether to speak at all: zero
1438
+ * means this reader has already been told about every one of them as often as
1439
+ * the cap allows.
1440
+ */
1441
+ export declare const AnnounceItemNotesResponseSchema: v.ObjectSchema<{
1442
+ /** Open, unmuted notes about the items these bundles deliver to this reader. */
1443
+ readonly open: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
1444
+ /** How many of those were under the cap and have now been counted as announced. */
1445
+ readonly announced: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
924
1446
  }, undefined>;
1447
+ export type AnnounceItemNotesResponse = v.InferOutput<typeof AnnounceItemNotesResponseSchema>;
1448
+ /**
1449
+ * One note on the on-demand read, with the item it is about named on the note.
1450
+ *
1451
+ * The item is named here rather than the notes riding an item, because this
1452
+ * read answers "what has been left for me" rather than "what is in this
1453
+ * bundle": there is no item payload to hang them off, and an agent that has to
1454
+ * ask for every item to find out whether one carries a note is the round trip
1455
+ * the announcement exists to avoid.
1456
+ */
1457
+ export declare const ItemNoteWithSubjectSchema: v.ObjectSchema<{
1458
+ /** The item the note is about, as the wire names it. */
1459
+ readonly itemName: v.StringSchema<undefined>;
1460
+ /** The item's declared repo-relative path, or null when it has none. */
1461
+ readonly itemPath: v.NullableSchema<v.StringSchema<undefined>, undefined>;
1462
+ readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
1463
+ /** The note's text, already wrapped in the response's untrusted markers. */
1464
+ readonly body: v.StringSchema<undefined>;
1465
+ /** The author's display name as the workspace shows it, or null. Never an email. */
1466
+ readonly authorName: v.NullableSchema<v.StringSchema<undefined>, undefined>;
1467
+ /** ISO timestamp, machine format. */
1468
+ readonly createdAt: v.StringSchema<undefined>;
1469
+ /** The item's content version the note was written against. */
1470
+ readonly itemVersion: v.NumberSchema<undefined>;
1471
+ /** True when the item's current version is greater than `itemVersion`. */
1472
+ readonly itemChangedSince: v.BooleanSchema<undefined>;
1473
+ /**
1474
+ * How many agent reads were handed this note **before** this one — so a
1475
+ * note reaching an agent for the first time reports `0`.
1476
+ *
1477
+ * It is the stored count as it read at the moment the response was built;
1478
+ * the serve this response *is* has not been counted yet. Excluded rather
1479
+ * than included because the count is recorded best-effort: a response that
1480
+ * claimed to include itself would be wrong whenever that record failed, and
1481
+ * a number that is sometimes off by one is worse than one that is
1482
+ * consistently the prior total.
1483
+ *
1484
+ * So `deliveredCount > 0` means an earlier read was handed this note, and
1485
+ * `0` means this read is the first. Neither says a model took it in — only
1486
+ * that the server handed it over.
1487
+ */
1488
+ readonly deliveredCount: v.NumberSchema<undefined>;
1489
+ /**
1490
+ * This note's thread root — its own id for every note written today, since
1491
+ * no reply exists yet. Ignorable now; load-bearing once a reply is a second
1492
+ * row with a different id here. It is on the wire from the first response
1493
+ * because the wire contract is consumed by installed CLI versions: reshaping
1494
+ * a flat `notes` array into threads-of-notes later would be a breaking
1495
+ * change, while a field today's readers ignore costs them nothing.
1496
+ */
1497
+ readonly threadId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
1498
+ /**
1499
+ * Always `null` today — no reply exists to point at. Present now so an older
1500
+ * reader meeting a future response that carries real replies degrades to
1501
+ * "a flat list of notes" rather than failing to parse.
1502
+ */
1503
+ readonly replyToId: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, undefined>;
1504
+ }, undefined>;
1505
+ export type ItemNoteWithSubject = v.InferOutput<typeof ItemNoteWithSubjectSchema>;
1506
+ /**
1507
+ * Every open note waiting for this reader across the bundles they named.
1508
+ *
1509
+ * **This read is a delivery and is counted as one**, exactly as notes riding
1510
+ * an item are: a body reached an agent. What it is *not* is an announcement —
1511
+ * nothing here touches the per-repo announcement count, so asking to read your
1512
+ * notes never spends the interruptions the hook is allowed.
1513
+ *
1514
+ * **Never capped.** The announcement cap governs whether a hook speaks; a
1515
+ * reader who asked is owed every open note, and hiding one here would retire a
1516
+ * person's request without anybody deciding to.
1517
+ */
1518
+ export declare const ItemNotesResponseSchema: v.ObjectSchema<{
1519
+ readonly notes: v.ArraySchema<v.ObjectSchema<{
1520
+ /** The item the note is about, as the wire names it. */
1521
+ readonly itemName: v.StringSchema<undefined>;
1522
+ /** The item's declared repo-relative path, or null when it has none. */
1523
+ readonly itemPath: v.NullableSchema<v.StringSchema<undefined>, undefined>;
1524
+ readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
1525
+ /** The note's text, already wrapped in the response's untrusted markers. */
1526
+ readonly body: v.StringSchema<undefined>;
1527
+ /** The author's display name as the workspace shows it, or null. Never an email. */
1528
+ readonly authorName: v.NullableSchema<v.StringSchema<undefined>, undefined>;
1529
+ /** ISO timestamp, machine format. */
1530
+ readonly createdAt: v.StringSchema<undefined>;
1531
+ /** The item's content version the note was written against. */
1532
+ readonly itemVersion: v.NumberSchema<undefined>;
1533
+ /** True when the item's current version is greater than `itemVersion`. */
1534
+ readonly itemChangedSince: v.BooleanSchema<undefined>;
1535
+ /**
1536
+ * How many agent reads were handed this note **before** this one — so a
1537
+ * note reaching an agent for the first time reports `0`.
1538
+ *
1539
+ * It is the stored count as it read at the moment the response was built;
1540
+ * the serve this response *is* has not been counted yet. Excluded rather
1541
+ * than included because the count is recorded best-effort: a response that
1542
+ * claimed to include itself would be wrong whenever that record failed, and
1543
+ * a number that is sometimes off by one is worse than one that is
1544
+ * consistently the prior total.
1545
+ *
1546
+ * So `deliveredCount > 0` means an earlier read was handed this note, and
1547
+ * `0` means this read is the first. Neither says a model took it in — only
1548
+ * that the server handed it over.
1549
+ */
1550
+ readonly deliveredCount: v.NumberSchema<undefined>;
1551
+ /**
1552
+ * This note's thread root — its own id for every note written today, since
1553
+ * no reply exists yet. Ignorable now; load-bearing once a reply is a second
1554
+ * row with a different id here. It is on the wire from the first response
1555
+ * because the wire contract is consumed by installed CLI versions: reshaping
1556
+ * a flat `notes` array into threads-of-notes later would be a breaking
1557
+ * change, while a field today's readers ignore costs them nothing.
1558
+ */
1559
+ readonly threadId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
1560
+ /**
1561
+ * Always `null` today — no reply exists to point at. Present now so an older
1562
+ * reader meeting a future response that carries real replies degrades to
1563
+ * "a flat list of notes" rather than failing to parse.
1564
+ */
1565
+ readonly replyToId: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, undefined>;
1566
+ }, undefined>, undefined>;
1567
+ /**
1568
+ * The markers every `body` above is wrapped in, plus a statement of what
1569
+ * they mean. Present exactly when at least one note came back.
1570
+ */
1571
+ readonly untrusted: v.OptionalSchema<v.NullableSchema<v.ObjectSchema<{
1572
+ readonly token: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
1573
+ readonly startMarker: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
1574
+ readonly endMarker: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
1575
+ readonly note: v.StringSchema<undefined>;
1576
+ }, undefined>, undefined>, undefined>;
1577
+ }, undefined>;
1578
+ export type ItemNotesResponse = v.InferOutput<typeof ItemNotesResponseSchema>;
925
1579
  /** Max number of context item ids a push may cite as its transform sources. */
926
1580
  export declare const MAX_TRANSFORM_SOURCE_IDS = 100;
927
1581
  /**
@@ -934,7 +1588,7 @@ export declare const SourceItemIdsSchema: v.SchemaWithPipe<readonly [v.ArraySche
934
1588
  export declare const UpdatableSourceItemIdsSchema: v.SchemaWithPipe<readonly [v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, undefined>, v.MaxLengthAction<string[], 100, undefined>]>;
935
1589
  export declare const PushContextRequestSchema: v.ObjectSchema<{
936
1590
  readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 200, undefined>]>;
937
- readonly contentType: v.PicklistSchema<("document" | "reference" | "asset")[], undefined>;
1591
+ readonly contentType: v.PicklistSchema<("content" | "asset")[], undefined>;
938
1592
  readonly content: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.CheckAction<string, "content must be at most 262144 bytes">]>;
939
1593
  readonly itemId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
940
1594
  readonly origin: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
@@ -952,13 +1606,65 @@ export declare const PushContextRequestSchema: v.ObjectSchema<{
952
1606
  * a member of the bundle's workspace to reach this route at all.
953
1607
  */
954
1608
  readonly projectId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
1609
+ /**
1610
+ * Where the committed bytes in `content` came from, when this write is a
1611
+ * publication (`artifact-ownership-and-delivery-plan.md` → slice 3). Present
1612
+ * means git owns the resulting artifact: the commit is the authority and
1613
+ * Mossbear distributes the revision rather than keeping a second editable
1614
+ * copy.
1615
+ *
1616
+ * **Sending it is a claim about provenance, not an authorization.** The
1617
+ * server still answers who may write here from bundle membership and the
1618
+ * bundle's declared home, exactly as it does for `projectId` above; what this
1619
+ * adds is the revision the bytes were read from, so a subscriber can answer
1620
+ * "what did I get".
1621
+ *
1622
+ * **`path` is required alongside it and the route enforces that**, because
1623
+ * the database will: `guide_files_git_source_subset` admits only "repo id +
1624
+ * path + sha all present" or the whole group absent, so a publication that
1625
+ * named no path would fail at insert time with a constraint error instead of
1626
+ * a sentence. Refused in the route rather than restated as a wire rule, for
1627
+ * the reason `ContextItemSchema.gitSource` gives — a path this schema cannot
1628
+ * parse is one item's problem, not the response's.
1629
+ */
1630
+ readonly gitSource: v.OptionalSchema<v.ObjectSchema<{
1631
+ /**
1632
+ * The committed `project.id` of the source repository — the same id space as
1633
+ * an item's delivery-scoping `projectId` below, but a different fact: that one
1634
+ * says which repo an item is materialized into and is stamped onto
1635
+ * Mossbear-owned rows too, this one says who may edit it.
1636
+ */
1637
+ 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">]>;
1638
+ readonly commitSha: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "commitSha must be 40 or 64 lowercase hex characters">]>;
1639
+ /**
1640
+ * The branch the publishing commit was on. **The one optional member**:
1641
+ * publication is not restricted by branch, so this is recorded so a subscriber
1642
+ * can see what they got, and a detached HEAD has none to record.
1643
+ */
1644
+ readonly branch: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 255, undefined>]>, undefined>;
1645
+ }, undefined>, undefined>;
955
1646
  }, undefined>;
956
1647
  export declare const PushContextResponseSchema: v.ObjectSchema<{
957
1648
  readonly item: v.ObjectSchema<{
958
1649
  readonly id: v.StringSchema<undefined>;
959
1650
  readonly type: v.PicklistSchema<string[], undefined>;
960
1651
  readonly name: v.StringSchema<undefined>;
961
- readonly contentType: v.StringSchema<undefined>;
1652
+ /**
1653
+ * The stored `(role, format)` pair, as two bare nullable strings.
1654
+ *
1655
+ * **Both are deliberately unenumerated.** A client switches on one value it
1656
+ * cares about — `role === 'criteria'` is how a rubric is told from ordinary
1657
+ * prose, which `type` cannot say because a rubric serializes as a `document` —
1658
+ * and a server that adds a fourth role or a fifth format must not break a
1659
+ * client that has never heard of it. Narrowing them here would make every such
1660
+ * addition a breaking wire change for no reader's benefit.
1661
+ *
1662
+ * Null on exactly the rows that carry no content: a tombstone, and an alias.
1663
+ * A `guide` item has no pair at all — it is a different table — and reports
1664
+ * both as null.
1665
+ */
1666
+ readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
1667
+ readonly format: v.NullableSchema<v.StringSchema<undefined>, undefined>;
962
1668
  readonly content: v.NullableSchema<v.StringSchema<undefined>, undefined>;
963
1669
  readonly origin: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
964
1670
  readonly version: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
@@ -986,7 +1692,139 @@ export declare const PushContextResponseSchema: v.ObjectSchema<{
986
1692
  root: "project" | "global";
987
1693
  path: string;
988
1694
  }[], 8, undefined>]>, undefined>;
1695
+ /**
1696
+ * Open notes a person left about this item, newest first.
1697
+ *
1698
+ * Optional, and absent rather than empty when there are none — the same rule
1699
+ * `aliases` and `projectId` follow above, and for the same reason: an older
1700
+ * reader against a newer server ignores the key, and a newer reader against
1701
+ * an older server reads "no notes" instead of failing.
1702
+ *
1703
+ * **Absence is not a verdict.** No notes here means none were served on this
1704
+ * item in this response — not that nobody has anything to say about it.
1705
+ */
1706
+ readonly notes: v.OptionalSchema<v.SchemaWithPipe<readonly [v.ArraySchema<v.ObjectSchema<{
1707
+ readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
1708
+ /** The note's text, already wrapped in the response's untrusted markers. */
1709
+ readonly body: v.StringSchema<undefined>;
1710
+ /** The author's display name as the workspace shows it, or null. Never an email. */
1711
+ readonly authorName: v.NullableSchema<v.StringSchema<undefined>, undefined>;
1712
+ /** ISO timestamp, machine format. */
1713
+ readonly createdAt: v.StringSchema<undefined>;
1714
+ /** The item's content version the note was written against. */
1715
+ readonly itemVersion: v.NumberSchema<undefined>;
1716
+ /** True when the item's current version is greater than `itemVersion`. */
1717
+ readonly itemChangedSince: v.BooleanSchema<undefined>;
1718
+ /**
1719
+ * How many agent reads were handed this note **before** this one — so a
1720
+ * note reaching an agent for the first time reports `0`.
1721
+ *
1722
+ * It is the stored count as it read at the moment the response was built;
1723
+ * the serve this response *is* has not been counted yet. Excluded rather
1724
+ * than included because the count is recorded best-effort: a response that
1725
+ * claimed to include itself would be wrong whenever that record failed, and
1726
+ * a number that is sometimes off by one is worse than one that is
1727
+ * consistently the prior total.
1728
+ *
1729
+ * So `deliveredCount > 0` means an earlier read was handed this note, and
1730
+ * `0` means this read is the first. Neither says a model took it in — only
1731
+ * that the server handed it over.
1732
+ */
1733
+ readonly deliveredCount: v.NumberSchema<undefined>;
1734
+ /**
1735
+ * This note's thread root — its own id for every note written today, since
1736
+ * no reply exists yet. Ignorable now; load-bearing once a reply is a second
1737
+ * row with a different id here. It is on the wire from the first response
1738
+ * because the wire contract is consumed by installed CLI versions: reshaping
1739
+ * a flat `notes` array into threads-of-notes later would be a breaking
1740
+ * change, while a field today's readers ignore costs them nothing.
1741
+ */
1742
+ readonly threadId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
1743
+ /**
1744
+ * Always `null` today — no reply exists to point at. Present now so an older
1745
+ * reader meeting a future response that carries real replies degrades to
1746
+ * "a flat list of notes" rather than failing to parse.
1747
+ */
1748
+ readonly replyToId: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, undefined>;
1749
+ }, undefined>, undefined>, v.MaxLengthAction<{
1750
+ id: string;
1751
+ body: string;
1752
+ authorName: string | null;
1753
+ createdAt: string;
1754
+ itemVersion: number;
1755
+ itemChangedSince: boolean;
1756
+ deliveredCount: number;
1757
+ threadId: string;
1758
+ replyToId: string | null;
1759
+ }[], 20, undefined>]>, undefined>;
989
1760
  readonly updatedAt: v.StringSchema<undefined>;
1761
+ /**
1762
+ * Present iff this artifact is owned by git. Absent means Mossbear owns it
1763
+ * and it is editable in the dashboard.
1764
+ *
1765
+ * **Optional, and absence is not yet a verdict.** Nothing writes this before
1766
+ * `publish` ships, so today every item omits it, and the existing bundle-home
1767
+ * rule — a bundle may name one repo as its only writer, and the server
1768
+ * refuses every other writer by name — is what still protects items a repo
1769
+ * already owns. A reader must not treat an absent `gitSource` as permission
1770
+ * to publish back.
1771
+ *
1772
+ * **Optional *and* nullable, like every other late-added column on this item.**
1773
+ * A serializer that maps the columns straight through emits `null` for a
1774
+ * Mossbear-owned row, and a key that only accepted `undefined` would throw on
1775
+ * the whole response rather than on the one item — `parseContextItemsResponse`
1776
+ * parses a pull as a batch. Both spellings read the same way: no git source.
1777
+ *
1778
+ * **`path` is the third required member of the subset and is not re-checked
1779
+ * here.** The database holds that invariant
1780
+ * (`guide_files_git_source_subset`), and a wire rule that looked identical
1781
+ * would in fact be stricter: `path` is serialized through a scope helper that
1782
+ * emits `null` for a path this schema cannot parse, so a single such row would
1783
+ * fail every other item in the same pull. A git-owned item that arrives
1784
+ * without a usable path is a broken item, not a broken response.
1785
+ */
1786
+ readonly gitSource: v.OptionalSchema<v.NullableSchema<v.ObjectSchema<{
1787
+ /**
1788
+ * The committed `project.id` of the source repository — the same id space as
1789
+ * an item's delivery-scoping `projectId` below, but a different fact: that one
1790
+ * says which repo an item is materialized into and is stamped onto
1791
+ * Mossbear-owned rows too, this one says who may edit it.
1792
+ */
1793
+ 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">]>;
1794
+ readonly commitSha: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "commitSha must be 40 or 64 lowercase hex characters">]>;
1795
+ /**
1796
+ * The branch the publishing commit was on. **The one optional member**:
1797
+ * publication is not restricted by branch, so this is recorded so a subscriber
1798
+ * can see what they got, and a detached HEAD has none to record.
1799
+ */
1800
+ readonly branch: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 255, undefined>]>, undefined>;
1801
+ }, undefined>, undefined>, undefined>;
1802
+ /**
1803
+ * This artifact is a **tombstone**: the repository that publishes it deleted
1804
+ * the file, so what the item still carries is the last revision rather than a
1805
+ * current one (`artifact-ownership-and-delivery-plan.md` → D28).
1806
+ *
1807
+ * **It is still delivered, and that is deliberate.** Dropping the item from
1808
+ * the response would say the same thing more quietly and cost two things
1809
+ * worth more than the byte: the publishing repo would lose the id it needs to
1810
+ * republish the path in place — re-adding a deleted file would create a
1811
+ * second artifact at the same path rather than a new revision of the one
1812
+ * that is there — and a reader would be left unable to tell a removal from
1813
+ * a bundle it has stopped being able to see. What the flag asks of a client
1814
+ * is one thing: do not materialize it. A file left at a discovery root keeps
1815
+ * feeding deleted guidance into every agent that reads that repo, which is
1816
+ * the failure the decision exists to stop.
1817
+ *
1818
+ * **Optional, and absent means an ordinary artifact.** A client that has
1819
+ * never heard of it behaves as it always did — it keeps the last published
1820
+ * revision on disk, which is the retain behaviour this replaces rather than a
1821
+ * new failure. That is what makes the server safe to ship first.
1822
+ *
1823
+ * `literal(true)` rather than a boolean: `removed: false` would be a second
1824
+ * spelling of absence, and an artifact that came back is content again rather
1825
+ * than a tombstone that says no.
1826
+ */
1827
+ readonly removed: v.OptionalSchema<v.LiteralSchema<true, undefined>, undefined>;
990
1828
  }, undefined>;
991
1829
  readonly created: v.BooleanSchema<undefined>;
992
1830
  }, undefined>;
@@ -1003,13 +1841,80 @@ export declare const UpdateContextItemRequestSchema: v.ObjectSchema<{
1003
1841
  */
1004
1842
  readonly projectId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
1005
1843
  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>;
1844
+ /**
1845
+ * The revision this update's bytes were read from — same meaning as on
1846
+ * `PushContextRequestSchema` above, and the field that makes a republication
1847
+ * advance an artifact's provenance rather than leave it pointing at the
1848
+ * commit it was first published from.
1849
+ *
1850
+ * **Omitted leaves the stored group alone; it never clears it.** An update
1851
+ * that says nothing about provenance is a name or body edit, not a claim that
1852
+ * the artifact stopped being git-owned — and an absent key that silently
1853
+ * un-owned a row would hand a subscriber write access by omission, which is
1854
+ * the failure the whole ownership model exists to prevent. Ownership is given
1855
+ * up by promotion, not by a missing field.
1856
+ */
1857
+ readonly gitSource: v.OptionalSchema<v.ObjectSchema<{
1858
+ /**
1859
+ * The committed `project.id` of the source repository — the same id space as
1860
+ * an item's delivery-scoping `projectId` below, but a different fact: that one
1861
+ * says which repo an item is materialized into and is stamped onto
1862
+ * Mossbear-owned rows too, this one says who may edit it.
1863
+ */
1864
+ 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">]>;
1865
+ readonly commitSha: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "commitSha must be 40 or 64 lowercase hex characters">]>;
1866
+ /**
1867
+ * The branch the publishing commit was on. **The one optional member**:
1868
+ * publication is not restricted by branch, so this is recorded so a subscriber
1869
+ * can see what they got, and a detached HEAD has none to record.
1870
+ */
1871
+ readonly branch: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 255, undefined>]>, undefined>;
1872
+ }, undefined>, undefined>;
1873
+ /**
1874
+ * Tombstone this artifact: the commit that published it has since deleted the
1875
+ * file, so the revision stops being delivered while the row and its version
1876
+ * history stay where they are.
1877
+ *
1878
+ * **A verb, not a column state**, the same shape the dashboard's own removal
1879
+ * takes (`~/zero/mutators.ts` → `guideFiles.update`'s `removed`). There is no
1880
+ * writable field here that a removal and an ordinary edit could disagree
1881
+ * about, and `literal(true)` is what keeps `removed: false` from reading as a
1882
+ * request to bring something back — un-removing is republishing, which is an
1883
+ * ordinary content write.
1884
+ *
1885
+ * **`gitSource` is required alongside it and the route enforces that.** A
1886
+ * tombstone's whole claim is *which revision removed the file*: without one
1887
+ * the row would say an artifact stopped being delivered and be unable to say
1888
+ * why, which is the silent withdrawal this field exists to replace. That also
1889
+ * keeps the only writer of a removal here the publication path — this is not
1890
+ * a general delete verb for the context layer.
1891
+ *
1892
+ * **Never sent with `content`.** A removal has no bytes; a body carrying both
1893
+ * is two answers to one question and the route refuses it rather than picking.
1894
+ */
1895
+ readonly removed: v.OptionalSchema<v.LiteralSchema<true, undefined>, undefined>;
1006
1896
  }, undefined>;
1007
1897
  export declare const UpdateContextItemResponseSchema: v.ObjectSchema<{
1008
1898
  readonly item: v.ObjectSchema<{
1009
1899
  readonly id: v.StringSchema<undefined>;
1010
1900
  readonly type: v.PicklistSchema<string[], undefined>;
1011
1901
  readonly name: v.StringSchema<undefined>;
1012
- readonly contentType: v.StringSchema<undefined>;
1902
+ /**
1903
+ * The stored `(role, format)` pair, as two bare nullable strings.
1904
+ *
1905
+ * **Both are deliberately unenumerated.** A client switches on one value it
1906
+ * cares about — `role === 'criteria'` is how a rubric is told from ordinary
1907
+ * prose, which `type` cannot say because a rubric serializes as a `document` —
1908
+ * and a server that adds a fourth role or a fifth format must not break a
1909
+ * client that has never heard of it. Narrowing them here would make every such
1910
+ * addition a breaking wire change for no reader's benefit.
1911
+ *
1912
+ * Null on exactly the rows that carry no content: a tombstone, and an alias.
1913
+ * A `guide` item has no pair at all — it is a different table — and reports
1914
+ * both as null.
1915
+ */
1916
+ readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
1917
+ readonly format: v.NullableSchema<v.StringSchema<undefined>, undefined>;
1013
1918
  readonly content: v.NullableSchema<v.StringSchema<undefined>, undefined>;
1014
1919
  readonly origin: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
1015
1920
  readonly version: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
@@ -1037,7 +1942,139 @@ export declare const UpdateContextItemResponseSchema: v.ObjectSchema<{
1037
1942
  root: "project" | "global";
1038
1943
  path: string;
1039
1944
  }[], 8, undefined>]>, undefined>;
1945
+ /**
1946
+ * Open notes a person left about this item, newest first.
1947
+ *
1948
+ * Optional, and absent rather than empty when there are none — the same rule
1949
+ * `aliases` and `projectId` follow above, and for the same reason: an older
1950
+ * reader against a newer server ignores the key, and a newer reader against
1951
+ * an older server reads "no notes" instead of failing.
1952
+ *
1953
+ * **Absence is not a verdict.** No notes here means none were served on this
1954
+ * item in this response — not that nobody has anything to say about it.
1955
+ */
1956
+ readonly notes: v.OptionalSchema<v.SchemaWithPipe<readonly [v.ArraySchema<v.ObjectSchema<{
1957
+ readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
1958
+ /** The note's text, already wrapped in the response's untrusted markers. */
1959
+ readonly body: v.StringSchema<undefined>;
1960
+ /** The author's display name as the workspace shows it, or null. Never an email. */
1961
+ readonly authorName: v.NullableSchema<v.StringSchema<undefined>, undefined>;
1962
+ /** ISO timestamp, machine format. */
1963
+ readonly createdAt: v.StringSchema<undefined>;
1964
+ /** The item's content version the note was written against. */
1965
+ readonly itemVersion: v.NumberSchema<undefined>;
1966
+ /** True when the item's current version is greater than `itemVersion`. */
1967
+ readonly itemChangedSince: v.BooleanSchema<undefined>;
1968
+ /**
1969
+ * How many agent reads were handed this note **before** this one — so a
1970
+ * note reaching an agent for the first time reports `0`.
1971
+ *
1972
+ * It is the stored count as it read at the moment the response was built;
1973
+ * the serve this response *is* has not been counted yet. Excluded rather
1974
+ * than included because the count is recorded best-effort: a response that
1975
+ * claimed to include itself would be wrong whenever that record failed, and
1976
+ * a number that is sometimes off by one is worse than one that is
1977
+ * consistently the prior total.
1978
+ *
1979
+ * So `deliveredCount > 0` means an earlier read was handed this note, and
1980
+ * `0` means this read is the first. Neither says a model took it in — only
1981
+ * that the server handed it over.
1982
+ */
1983
+ readonly deliveredCount: v.NumberSchema<undefined>;
1984
+ /**
1985
+ * This note's thread root — its own id for every note written today, since
1986
+ * no reply exists yet. Ignorable now; load-bearing once a reply is a second
1987
+ * row with a different id here. It is on the wire from the first response
1988
+ * because the wire contract is consumed by installed CLI versions: reshaping
1989
+ * a flat `notes` array into threads-of-notes later would be a breaking
1990
+ * change, while a field today's readers ignore costs them nothing.
1991
+ */
1992
+ readonly threadId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
1993
+ /**
1994
+ * Always `null` today — no reply exists to point at. Present now so an older
1995
+ * reader meeting a future response that carries real replies degrades to
1996
+ * "a flat list of notes" rather than failing to parse.
1997
+ */
1998
+ readonly replyToId: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, undefined>;
1999
+ }, undefined>, undefined>, v.MaxLengthAction<{
2000
+ id: string;
2001
+ body: string;
2002
+ authorName: string | null;
2003
+ createdAt: string;
2004
+ itemVersion: number;
2005
+ itemChangedSince: boolean;
2006
+ deliveredCount: number;
2007
+ threadId: string;
2008
+ replyToId: string | null;
2009
+ }[], 20, undefined>]>, undefined>;
1040
2010
  readonly updatedAt: v.StringSchema<undefined>;
2011
+ /**
2012
+ * Present iff this artifact is owned by git. Absent means Mossbear owns it
2013
+ * and it is editable in the dashboard.
2014
+ *
2015
+ * **Optional, and absence is not yet a verdict.** Nothing writes this before
2016
+ * `publish` ships, so today every item omits it, and the existing bundle-home
2017
+ * rule — a bundle may name one repo as its only writer, and the server
2018
+ * refuses every other writer by name — is what still protects items a repo
2019
+ * already owns. A reader must not treat an absent `gitSource` as permission
2020
+ * to publish back.
2021
+ *
2022
+ * **Optional *and* nullable, like every other late-added column on this item.**
2023
+ * A serializer that maps the columns straight through emits `null` for a
2024
+ * Mossbear-owned row, and a key that only accepted `undefined` would throw on
2025
+ * the whole response rather than on the one item — `parseContextItemsResponse`
2026
+ * parses a pull as a batch. Both spellings read the same way: no git source.
2027
+ *
2028
+ * **`path` is the third required member of the subset and is not re-checked
2029
+ * here.** The database holds that invariant
2030
+ * (`guide_files_git_source_subset`), and a wire rule that looked identical
2031
+ * would in fact be stricter: `path` is serialized through a scope helper that
2032
+ * emits `null` for a path this schema cannot parse, so a single such row would
2033
+ * fail every other item in the same pull. A git-owned item that arrives
2034
+ * without a usable path is a broken item, not a broken response.
2035
+ */
2036
+ readonly gitSource: v.OptionalSchema<v.NullableSchema<v.ObjectSchema<{
2037
+ /**
2038
+ * The committed `project.id` of the source repository — the same id space as
2039
+ * an item's delivery-scoping `projectId` below, but a different fact: that one
2040
+ * says which repo an item is materialized into and is stamped onto
2041
+ * Mossbear-owned rows too, this one says who may edit it.
2042
+ */
2043
+ 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">]>;
2044
+ readonly commitSha: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "commitSha must be 40 or 64 lowercase hex characters">]>;
2045
+ /**
2046
+ * The branch the publishing commit was on. **The one optional member**:
2047
+ * publication is not restricted by branch, so this is recorded so a subscriber
2048
+ * can see what they got, and a detached HEAD has none to record.
2049
+ */
2050
+ readonly branch: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 255, undefined>]>, undefined>;
2051
+ }, undefined>, undefined>, undefined>;
2052
+ /**
2053
+ * This artifact is a **tombstone**: the repository that publishes it deleted
2054
+ * the file, so what the item still carries is the last revision rather than a
2055
+ * current one (`artifact-ownership-and-delivery-plan.md` → D28).
2056
+ *
2057
+ * **It is still delivered, and that is deliberate.** Dropping the item from
2058
+ * the response would say the same thing more quietly and cost two things
2059
+ * worth more than the byte: the publishing repo would lose the id it needs to
2060
+ * republish the path in place — re-adding a deleted file would create a
2061
+ * second artifact at the same path rather than a new revision of the one
2062
+ * that is there — and a reader would be left unable to tell a removal from
2063
+ * a bundle it has stopped being able to see. What the flag asks of a client
2064
+ * is one thing: do not materialize it. A file left at a discovery root keeps
2065
+ * feeding deleted guidance into every agent that reads that repo, which is
2066
+ * the failure the decision exists to stop.
2067
+ *
2068
+ * **Optional, and absent means an ordinary artifact.** A client that has
2069
+ * never heard of it behaves as it always did — it keeps the last published
2070
+ * revision on disk, which is the retain behaviour this replaces rather than a
2071
+ * new failure. That is what makes the server safe to ship first.
2072
+ *
2073
+ * `literal(true)` rather than a boolean: `removed: false` would be a second
2074
+ * spelling of absence, and an artifact that came back is content again rather
2075
+ * than a tombstone that says no.
2076
+ */
2077
+ readonly removed: v.OptionalSchema<v.LiteralSchema<true, undefined>, undefined>;
1041
2078
  }, undefined>;
1042
2079
  readonly updated: v.BooleanSchema<undefined>;
1043
2080
  }, undefined>;
@@ -1054,6 +2091,58 @@ export declare const UpdateContextItemBodySchema: Omit<v.ObjectSchema<{
1054
2091
  */
1055
2092
  readonly projectId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
1056
2093
  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>;
2094
+ /**
2095
+ * The revision this update's bytes were read from — same meaning as on
2096
+ * `PushContextRequestSchema` above, and the field that makes a republication
2097
+ * advance an artifact's provenance rather than leave it pointing at the
2098
+ * commit it was first published from.
2099
+ *
2100
+ * **Omitted leaves the stored group alone; it never clears it.** An update
2101
+ * that says nothing about provenance is a name or body edit, not a claim that
2102
+ * the artifact stopped being git-owned — and an absent key that silently
2103
+ * un-owned a row would hand a subscriber write access by omission, which is
2104
+ * the failure the whole ownership model exists to prevent. Ownership is given
2105
+ * up by promotion, not by a missing field.
2106
+ */
2107
+ readonly gitSource: v.OptionalSchema<v.ObjectSchema<{
2108
+ /**
2109
+ * The committed `project.id` of the source repository — the same id space as
2110
+ * an item's delivery-scoping `projectId` below, but a different fact: that one
2111
+ * says which repo an item is materialized into and is stamped onto
2112
+ * Mossbear-owned rows too, this one says who may edit it.
2113
+ */
2114
+ 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">]>;
2115
+ readonly commitSha: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "commitSha must be 40 or 64 lowercase hex characters">]>;
2116
+ /**
2117
+ * The branch the publishing commit was on. **The one optional member**:
2118
+ * publication is not restricted by branch, so this is recorded so a subscriber
2119
+ * can see what they got, and a detached HEAD has none to record.
2120
+ */
2121
+ readonly branch: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 255, undefined>]>, undefined>;
2122
+ }, undefined>, undefined>;
2123
+ /**
2124
+ * Tombstone this artifact: the commit that published it has since deleted the
2125
+ * file, so the revision stops being delivered while the row and its version
2126
+ * history stay where they are.
2127
+ *
2128
+ * **A verb, not a column state**, the same shape the dashboard's own removal
2129
+ * takes (`~/zero/mutators.ts` → `guideFiles.update`'s `removed`). There is no
2130
+ * writable field here that a removal and an ordinary edit could disagree
2131
+ * about, and `literal(true)` is what keeps `removed: false` from reading as a
2132
+ * request to bring something back — un-removing is republishing, which is an
2133
+ * ordinary content write.
2134
+ *
2135
+ * **`gitSource` is required alongside it and the route enforces that.** A
2136
+ * tombstone's whole claim is *which revision removed the file*: without one
2137
+ * the row would say an artifact stopped being delivered and be unable to say
2138
+ * why, which is the silent withdrawal this field exists to replace. That also
2139
+ * keeps the only writer of a removal here the publication path — this is not
2140
+ * a general delete verb for the context layer.
2141
+ *
2142
+ * **Never sent with `content`.** A removal has no bytes; a body carrying both
2143
+ * is two answers to one question and the route refuses it rather than picking.
2144
+ */
2145
+ readonly removed: v.OptionalSchema<v.LiteralSchema<true, undefined>, undefined>;
1057
2146
  }, undefined>, "entries" | "~types" | "~run" | "~standard"> & {
1058
2147
  readonly entries: Omit<{
1059
2148
  readonly itemId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
@@ -1068,18 +2157,82 @@ export declare const UpdateContextItemBodySchema: Omit<v.ObjectSchema<{
1068
2157
  */
1069
2158
  readonly projectId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
1070
2159
  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>;
2160
+ /**
2161
+ * The revision this update's bytes were read from — same meaning as on
2162
+ * `PushContextRequestSchema` above, and the field that makes a republication
2163
+ * advance an artifact's provenance rather than leave it pointing at the
2164
+ * commit it was first published from.
2165
+ *
2166
+ * **Omitted leaves the stored group alone; it never clears it.** An update
2167
+ * that says nothing about provenance is a name or body edit, not a claim that
2168
+ * the artifact stopped being git-owned — and an absent key that silently
2169
+ * un-owned a row would hand a subscriber write access by omission, which is
2170
+ * the failure the whole ownership model exists to prevent. Ownership is given
2171
+ * up by promotion, not by a missing field.
2172
+ */
2173
+ readonly gitSource: v.OptionalSchema<v.ObjectSchema<{
2174
+ /**
2175
+ * The committed `project.id` of the source repository — the same id space as
2176
+ * an item's delivery-scoping `projectId` below, but a different fact: that one
2177
+ * says which repo an item is materialized into and is stamped onto
2178
+ * Mossbear-owned rows too, this one says who may edit it.
2179
+ */
2180
+ 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">]>;
2181
+ readonly commitSha: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "commitSha must be 40 or 64 lowercase hex characters">]>;
2182
+ /**
2183
+ * The branch the publishing commit was on. **The one optional member**:
2184
+ * publication is not restricted by branch, so this is recorded so a subscriber
2185
+ * can see what they got, and a detached HEAD has none to record.
2186
+ */
2187
+ readonly branch: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 255, undefined>]>, undefined>;
2188
+ }, undefined>, undefined>;
2189
+ /**
2190
+ * Tombstone this artifact: the commit that published it has since deleted the
2191
+ * file, so the revision stops being delivered while the row and its version
2192
+ * history stay where they are.
2193
+ *
2194
+ * **A verb, not a column state**, the same shape the dashboard's own removal
2195
+ * takes (`~/zero/mutators.ts` → `guideFiles.update`'s `removed`). There is no
2196
+ * writable field here that a removal and an ordinary edit could disagree
2197
+ * about, and `literal(true)` is what keeps `removed: false` from reading as a
2198
+ * request to bring something back — un-removing is republishing, which is an
2199
+ * ordinary content write.
2200
+ *
2201
+ * **`gitSource` is required alongside it and the route enforces that.** A
2202
+ * tombstone's whole claim is *which revision removed the file*: without one
2203
+ * the row would say an artifact stopped being delivered and be unable to say
2204
+ * why, which is the silent withdrawal this field exists to replace. That also
2205
+ * keeps the only writer of a removal here the publication path — this is not
2206
+ * a general delete verb for the context layer.
2207
+ *
2208
+ * **Never sent with `content`.** A removal has no bytes; a body carrying both
2209
+ * is two answers to one question and the route refuses it rather than picking.
2210
+ */
2211
+ readonly removed: v.OptionalSchema<v.LiteralSchema<true, undefined>, undefined>;
1071
2212
  }, "itemId">;
1072
2213
  readonly "~standard": v.StandardProps<{
1073
2214
  name?: string | undefined;
1074
2215
  content?: string | undefined;
1075
2216
  expectedVersion?: number | undefined;
1076
2217
  projectId?: string | undefined;
2218
+ gitSource?: {
2219
+ projectId: string;
2220
+ commitSha: string;
2221
+ branch?: string | undefined;
2222
+ } | undefined;
2223
+ removed?: true | undefined;
1077
2224
  sourceItemIds?: string[] | undefined;
1078
2225
  }, {
1079
2226
  name?: string | undefined;
1080
2227
  content?: string | undefined;
1081
2228
  expectedVersion?: number | undefined;
1082
2229
  projectId?: string | undefined;
2230
+ gitSource?: {
2231
+ projectId: string;
2232
+ commitSha: string;
2233
+ branch?: string | undefined;
2234
+ } | undefined;
2235
+ removed?: true | undefined;
1083
2236
  sourceItemIds?: string[] | undefined;
1084
2237
  }>;
1085
2238
  readonly "~run": (dataset: v.UnknownDataset, config: v.Config<v.BaseIssue<unknown>>) => v.OutputDataset<{
@@ -1087,14 +2240,26 @@ export declare const UpdateContextItemBodySchema: Omit<v.ObjectSchema<{
1087
2240
  content?: string | undefined;
1088
2241
  expectedVersion?: number | undefined;
1089
2242
  projectId?: string | undefined;
2243
+ gitSource?: {
2244
+ projectId: string;
2245
+ commitSha: string;
2246
+ branch?: string | undefined;
2247
+ } | undefined;
2248
+ removed?: true | undefined;
1090
2249
  sourceItemIds?: string[] | undefined;
1091
- }, v.StringIssue | v.MinLengthIssue<string, 1> | v.CheckIssue<string> | v.NumberIssue | v.IntegerIssue<number> | v.ArrayIssue | v.ObjectIssue | v.MinValueIssue<number, 1> | v.MaxLengthIssue<string, 200> | v.MaxLengthIssue<string[], 100>>;
2250
+ }, v.StringIssue | v.MinLengthIssue<string, 1> | v.RegexIssue<string> | v.CheckIssue<string> | v.NumberIssue | v.IntegerIssue<number> | v.ArrayIssue | v.ObjectIssue | v.MinValueIssue<number, 1> | v.MaxLengthIssue<string, 128> | v.MaxLengthIssue<string, 200> | v.MaxLengthIssue<string, 255> | v.LiteralIssue | v.MaxLengthIssue<string[], 100>>;
1092
2251
  readonly "~types"?: {
1093
2252
  readonly input: {
1094
2253
  name?: string | undefined;
1095
2254
  content?: string | undefined;
1096
2255
  expectedVersion?: number | undefined;
1097
2256
  projectId?: string | undefined;
2257
+ gitSource?: {
2258
+ projectId: string;
2259
+ commitSha: string;
2260
+ branch?: string | undefined;
2261
+ } | undefined;
2262
+ removed?: true | undefined;
1098
2263
  sourceItemIds?: string[] | undefined;
1099
2264
  };
1100
2265
  readonly output: {
@@ -1102,9 +2267,15 @@ export declare const UpdateContextItemBodySchema: Omit<v.ObjectSchema<{
1102
2267
  content?: string | undefined;
1103
2268
  expectedVersion?: number | undefined;
1104
2269
  projectId?: string | undefined;
2270
+ gitSource?: {
2271
+ projectId: string;
2272
+ commitSha: string;
2273
+ branch?: string | undefined;
2274
+ } | undefined;
2275
+ removed?: true | undefined;
1105
2276
  sourceItemIds?: string[] | undefined;
1106
2277
  };
1107
- readonly issue: v.StringIssue | v.MinLengthIssue<string, 1> | v.CheckIssue<string> | v.NumberIssue | v.IntegerIssue<number> | v.ArrayIssue | v.ObjectIssue | v.MinValueIssue<number, 1> | v.MaxLengthIssue<string, 200> | v.MaxLengthIssue<string[], 100>;
2278
+ readonly issue: v.StringIssue | v.MinLengthIssue<string, 1> | v.RegexIssue<string> | v.CheckIssue<string> | v.NumberIssue | v.IntegerIssue<number> | v.ArrayIssue | v.ObjectIssue | v.MinValueIssue<number, 1> | v.MaxLengthIssue<string, 128> | v.MaxLengthIssue<string, 200> | v.MaxLengthIssue<string, 255> | v.LiteralIssue | v.MaxLengthIssue<string[], 100>;
1108
2279
  } | undefined;
1109
2280
  };
1110
2281
  /** A single canonical item, for the item-scoped read route. */
@@ -1113,7 +2284,22 @@ export declare const ContextItemResponseSchema: v.ObjectSchema<{
1113
2284
  readonly id: v.StringSchema<undefined>;
1114
2285
  readonly type: v.PicklistSchema<string[], undefined>;
1115
2286
  readonly name: v.StringSchema<undefined>;
1116
- readonly contentType: v.StringSchema<undefined>;
2287
+ /**
2288
+ * The stored `(role, format)` pair, as two bare nullable strings.
2289
+ *
2290
+ * **Both are deliberately unenumerated.** A client switches on one value it
2291
+ * cares about — `role === 'criteria'` is how a rubric is told from ordinary
2292
+ * prose, which `type` cannot say because a rubric serializes as a `document` —
2293
+ * and a server that adds a fourth role or a fifth format must not break a
2294
+ * client that has never heard of it. Narrowing them here would make every such
2295
+ * addition a breaking wire change for no reader's benefit.
2296
+ *
2297
+ * Null on exactly the rows that carry no content: a tombstone, and an alias.
2298
+ * A `guide` item has no pair at all — it is a different table — and reports
2299
+ * both as null.
2300
+ */
2301
+ readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
2302
+ readonly format: v.NullableSchema<v.StringSchema<undefined>, undefined>;
1117
2303
  readonly content: v.NullableSchema<v.StringSchema<undefined>, undefined>;
1118
2304
  readonly origin: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
1119
2305
  readonly version: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
@@ -1141,7 +2327,139 @@ export declare const ContextItemResponseSchema: v.ObjectSchema<{
1141
2327
  root: "project" | "global";
1142
2328
  path: string;
1143
2329
  }[], 8, undefined>]>, undefined>;
2330
+ /**
2331
+ * Open notes a person left about this item, newest first.
2332
+ *
2333
+ * Optional, and absent rather than empty when there are none — the same rule
2334
+ * `aliases` and `projectId` follow above, and for the same reason: an older
2335
+ * reader against a newer server ignores the key, and a newer reader against
2336
+ * an older server reads "no notes" instead of failing.
2337
+ *
2338
+ * **Absence is not a verdict.** No notes here means none were served on this
2339
+ * item in this response — not that nobody has anything to say about it.
2340
+ */
2341
+ readonly notes: v.OptionalSchema<v.SchemaWithPipe<readonly [v.ArraySchema<v.ObjectSchema<{
2342
+ readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
2343
+ /** The note's text, already wrapped in the response's untrusted markers. */
2344
+ readonly body: v.StringSchema<undefined>;
2345
+ /** The author's display name as the workspace shows it, or null. Never an email. */
2346
+ readonly authorName: v.NullableSchema<v.StringSchema<undefined>, undefined>;
2347
+ /** ISO timestamp, machine format. */
2348
+ readonly createdAt: v.StringSchema<undefined>;
2349
+ /** The item's content version the note was written against. */
2350
+ readonly itemVersion: v.NumberSchema<undefined>;
2351
+ /** True when the item's current version is greater than `itemVersion`. */
2352
+ readonly itemChangedSince: v.BooleanSchema<undefined>;
2353
+ /**
2354
+ * How many agent reads were handed this note **before** this one — so a
2355
+ * note reaching an agent for the first time reports `0`.
2356
+ *
2357
+ * It is the stored count as it read at the moment the response was built;
2358
+ * the serve this response *is* has not been counted yet. Excluded rather
2359
+ * than included because the count is recorded best-effort: a response that
2360
+ * claimed to include itself would be wrong whenever that record failed, and
2361
+ * a number that is sometimes off by one is worse than one that is
2362
+ * consistently the prior total.
2363
+ *
2364
+ * So `deliveredCount > 0` means an earlier read was handed this note, and
2365
+ * `0` means this read is the first. Neither says a model took it in — only
2366
+ * that the server handed it over.
2367
+ */
2368
+ readonly deliveredCount: v.NumberSchema<undefined>;
2369
+ /**
2370
+ * This note's thread root — its own id for every note written today, since
2371
+ * no reply exists yet. Ignorable now; load-bearing once a reply is a second
2372
+ * row with a different id here. It is on the wire from the first response
2373
+ * because the wire contract is consumed by installed CLI versions: reshaping
2374
+ * a flat `notes` array into threads-of-notes later would be a breaking
2375
+ * change, while a field today's readers ignore costs them nothing.
2376
+ */
2377
+ readonly threadId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
2378
+ /**
2379
+ * Always `null` today — no reply exists to point at. Present now so an older
2380
+ * reader meeting a future response that carries real replies degrades to
2381
+ * "a flat list of notes" rather than failing to parse.
2382
+ */
2383
+ readonly replyToId: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, undefined>;
2384
+ }, undefined>, undefined>, v.MaxLengthAction<{
2385
+ id: string;
2386
+ body: string;
2387
+ authorName: string | null;
2388
+ createdAt: string;
2389
+ itemVersion: number;
2390
+ itemChangedSince: boolean;
2391
+ deliveredCount: number;
2392
+ threadId: string;
2393
+ replyToId: string | null;
2394
+ }[], 20, undefined>]>, undefined>;
1144
2395
  readonly updatedAt: v.StringSchema<undefined>;
2396
+ /**
2397
+ * Present iff this artifact is owned by git. Absent means Mossbear owns it
2398
+ * and it is editable in the dashboard.
2399
+ *
2400
+ * **Optional, and absence is not yet a verdict.** Nothing writes this before
2401
+ * `publish` ships, so today every item omits it, and the existing bundle-home
2402
+ * rule — a bundle may name one repo as its only writer, and the server
2403
+ * refuses every other writer by name — is what still protects items a repo
2404
+ * already owns. A reader must not treat an absent `gitSource` as permission
2405
+ * to publish back.
2406
+ *
2407
+ * **Optional *and* nullable, like every other late-added column on this item.**
2408
+ * A serializer that maps the columns straight through emits `null` for a
2409
+ * Mossbear-owned row, and a key that only accepted `undefined` would throw on
2410
+ * the whole response rather than on the one item — `parseContextItemsResponse`
2411
+ * parses a pull as a batch. Both spellings read the same way: no git source.
2412
+ *
2413
+ * **`path` is the third required member of the subset and is not re-checked
2414
+ * here.** The database holds that invariant
2415
+ * (`guide_files_git_source_subset`), and a wire rule that looked identical
2416
+ * would in fact be stricter: `path` is serialized through a scope helper that
2417
+ * emits `null` for a path this schema cannot parse, so a single such row would
2418
+ * fail every other item in the same pull. A git-owned item that arrives
2419
+ * without a usable path is a broken item, not a broken response.
2420
+ */
2421
+ readonly gitSource: v.OptionalSchema<v.NullableSchema<v.ObjectSchema<{
2422
+ /**
2423
+ * The committed `project.id` of the source repository — the same id space as
2424
+ * an item's delivery-scoping `projectId` below, but a different fact: that one
2425
+ * says which repo an item is materialized into and is stamped onto
2426
+ * Mossbear-owned rows too, this one says who may edit it.
2427
+ */
2428
+ 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">]>;
2429
+ readonly commitSha: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "commitSha must be 40 or 64 lowercase hex characters">]>;
2430
+ /**
2431
+ * The branch the publishing commit was on. **The one optional member**:
2432
+ * publication is not restricted by branch, so this is recorded so a subscriber
2433
+ * can see what they got, and a detached HEAD has none to record.
2434
+ */
2435
+ readonly branch: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 255, undefined>]>, undefined>;
2436
+ }, undefined>, undefined>, undefined>;
2437
+ /**
2438
+ * This artifact is a **tombstone**: the repository that publishes it deleted
2439
+ * the file, so what the item still carries is the last revision rather than a
2440
+ * current one (`artifact-ownership-and-delivery-plan.md` → D28).
2441
+ *
2442
+ * **It is still delivered, and that is deliberate.** Dropping the item from
2443
+ * the response would say the same thing more quietly and cost two things
2444
+ * worth more than the byte: the publishing repo would lose the id it needs to
2445
+ * republish the path in place — re-adding a deleted file would create a
2446
+ * second artifact at the same path rather than a new revision of the one
2447
+ * that is there — and a reader would be left unable to tell a removal from
2448
+ * a bundle it has stopped being able to see. What the flag asks of a client
2449
+ * is one thing: do not materialize it. A file left at a discovery root keeps
2450
+ * feeding deleted guidance into every agent that reads that repo, which is
2451
+ * the failure the decision exists to stop.
2452
+ *
2453
+ * **Optional, and absent means an ordinary artifact.** A client that has
2454
+ * never heard of it behaves as it always did — it keeps the last published
2455
+ * revision on disk, which is the retain behaviour this replaces rather than a
2456
+ * new failure. That is what makes the server safe to ship first.
2457
+ *
2458
+ * `literal(true)` rather than a boolean: `removed: false` would be a second
2459
+ * spelling of absence, and an artifact that came back is content again rather
2460
+ * than a tombstone that says no.
2461
+ */
2462
+ readonly removed: v.OptionalSchema<v.LiteralSchema<true, undefined>, undefined>;
1145
2463
  }, undefined>;
1146
2464
  }, undefined>;
1147
2465
  export declare const ArchiveContextItemResponseSchema: v.ObjectSchema<{
@@ -1150,7 +2468,22 @@ export declare const ArchiveContextItemResponseSchema: v.ObjectSchema<{
1150
2468
  readonly id: v.StringSchema<undefined>;
1151
2469
  readonly type: v.PicklistSchema<string[], undefined>;
1152
2470
  readonly name: v.StringSchema<undefined>;
1153
- readonly contentType: v.StringSchema<undefined>;
2471
+ /**
2472
+ * The stored `(role, format)` pair, as two bare nullable strings.
2473
+ *
2474
+ * **Both are deliberately unenumerated.** A client switches on one value it
2475
+ * cares about — `role === 'criteria'` is how a rubric is told from ordinary
2476
+ * prose, which `type` cannot say because a rubric serializes as a `document` —
2477
+ * and a server that adds a fourth role or a fifth format must not break a
2478
+ * client that has never heard of it. Narrowing them here would make every such
2479
+ * addition a breaking wire change for no reader's benefit.
2480
+ *
2481
+ * Null on exactly the rows that carry no content: a tombstone, and an alias.
2482
+ * A `guide` item has no pair at all — it is a different table — and reports
2483
+ * both as null.
2484
+ */
2485
+ readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
2486
+ readonly format: v.NullableSchema<v.StringSchema<undefined>, undefined>;
1154
2487
  readonly content: v.NullableSchema<v.StringSchema<undefined>, undefined>;
1155
2488
  readonly origin: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
1156
2489
  readonly version: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
@@ -1178,7 +2511,139 @@ export declare const ArchiveContextItemResponseSchema: v.ObjectSchema<{
1178
2511
  root: "project" | "global";
1179
2512
  path: string;
1180
2513
  }[], 8, undefined>]>, undefined>;
2514
+ /**
2515
+ * Open notes a person left about this item, newest first.
2516
+ *
2517
+ * Optional, and absent rather than empty when there are none — the same rule
2518
+ * `aliases` and `projectId` follow above, and for the same reason: an older
2519
+ * reader against a newer server ignores the key, and a newer reader against
2520
+ * an older server reads "no notes" instead of failing.
2521
+ *
2522
+ * **Absence is not a verdict.** No notes here means none were served on this
2523
+ * item in this response — not that nobody has anything to say about it.
2524
+ */
2525
+ readonly notes: v.OptionalSchema<v.SchemaWithPipe<readonly [v.ArraySchema<v.ObjectSchema<{
2526
+ readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
2527
+ /** The note's text, already wrapped in the response's untrusted markers. */
2528
+ readonly body: v.StringSchema<undefined>;
2529
+ /** The author's display name as the workspace shows it, or null. Never an email. */
2530
+ readonly authorName: v.NullableSchema<v.StringSchema<undefined>, undefined>;
2531
+ /** ISO timestamp, machine format. */
2532
+ readonly createdAt: v.StringSchema<undefined>;
2533
+ /** The item's content version the note was written against. */
2534
+ readonly itemVersion: v.NumberSchema<undefined>;
2535
+ /** True when the item's current version is greater than `itemVersion`. */
2536
+ readonly itemChangedSince: v.BooleanSchema<undefined>;
2537
+ /**
2538
+ * How many agent reads were handed this note **before** this one — so a
2539
+ * note reaching an agent for the first time reports `0`.
2540
+ *
2541
+ * It is the stored count as it read at the moment the response was built;
2542
+ * the serve this response *is* has not been counted yet. Excluded rather
2543
+ * than included because the count is recorded best-effort: a response that
2544
+ * claimed to include itself would be wrong whenever that record failed, and
2545
+ * a number that is sometimes off by one is worse than one that is
2546
+ * consistently the prior total.
2547
+ *
2548
+ * So `deliveredCount > 0` means an earlier read was handed this note, and
2549
+ * `0` means this read is the first. Neither says a model took it in — only
2550
+ * that the server handed it over.
2551
+ */
2552
+ readonly deliveredCount: v.NumberSchema<undefined>;
2553
+ /**
2554
+ * This note's thread root — its own id for every note written today, since
2555
+ * no reply exists yet. Ignorable now; load-bearing once a reply is a second
2556
+ * row with a different id here. It is on the wire from the first response
2557
+ * because the wire contract is consumed by installed CLI versions: reshaping
2558
+ * a flat `notes` array into threads-of-notes later would be a breaking
2559
+ * change, while a field today's readers ignore costs them nothing.
2560
+ */
2561
+ readonly threadId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
2562
+ /**
2563
+ * Always `null` today — no reply exists to point at. Present now so an older
2564
+ * reader meeting a future response that carries real replies degrades to
2565
+ * "a flat list of notes" rather than failing to parse.
2566
+ */
2567
+ readonly replyToId: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, undefined>;
2568
+ }, undefined>, undefined>, v.MaxLengthAction<{
2569
+ id: string;
2570
+ body: string;
2571
+ authorName: string | null;
2572
+ createdAt: string;
2573
+ itemVersion: number;
2574
+ itemChangedSince: boolean;
2575
+ deliveredCount: number;
2576
+ threadId: string;
2577
+ replyToId: string | null;
2578
+ }[], 20, undefined>]>, undefined>;
1181
2579
  readonly updatedAt: v.StringSchema<undefined>;
2580
+ /**
2581
+ * Present iff this artifact is owned by git. Absent means Mossbear owns it
2582
+ * and it is editable in the dashboard.
2583
+ *
2584
+ * **Optional, and absence is not yet a verdict.** Nothing writes this before
2585
+ * `publish` ships, so today every item omits it, and the existing bundle-home
2586
+ * rule — a bundle may name one repo as its only writer, and the server
2587
+ * refuses every other writer by name — is what still protects items a repo
2588
+ * already owns. A reader must not treat an absent `gitSource` as permission
2589
+ * to publish back.
2590
+ *
2591
+ * **Optional *and* nullable, like every other late-added column on this item.**
2592
+ * A serializer that maps the columns straight through emits `null` for a
2593
+ * Mossbear-owned row, and a key that only accepted `undefined` would throw on
2594
+ * the whole response rather than on the one item — `parseContextItemsResponse`
2595
+ * parses a pull as a batch. Both spellings read the same way: no git source.
2596
+ *
2597
+ * **`path` is the third required member of the subset and is not re-checked
2598
+ * here.** The database holds that invariant
2599
+ * (`guide_files_git_source_subset`), and a wire rule that looked identical
2600
+ * would in fact be stricter: `path` is serialized through a scope helper that
2601
+ * emits `null` for a path this schema cannot parse, so a single such row would
2602
+ * fail every other item in the same pull. A git-owned item that arrives
2603
+ * without a usable path is a broken item, not a broken response.
2604
+ */
2605
+ readonly gitSource: v.OptionalSchema<v.NullableSchema<v.ObjectSchema<{
2606
+ /**
2607
+ * The committed `project.id` of the source repository — the same id space as
2608
+ * an item's delivery-scoping `projectId` below, but a different fact: that one
2609
+ * says which repo an item is materialized into and is stamped onto
2610
+ * Mossbear-owned rows too, this one says who may edit it.
2611
+ */
2612
+ 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">]>;
2613
+ readonly commitSha: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "commitSha must be 40 or 64 lowercase hex characters">]>;
2614
+ /**
2615
+ * The branch the publishing commit was on. **The one optional member**:
2616
+ * publication is not restricted by branch, so this is recorded so a subscriber
2617
+ * can see what they got, and a detached HEAD has none to record.
2618
+ */
2619
+ readonly branch: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 255, undefined>]>, undefined>;
2620
+ }, undefined>, undefined>, undefined>;
2621
+ /**
2622
+ * This artifact is a **tombstone**: the repository that publishes it deleted
2623
+ * the file, so what the item still carries is the last revision rather than a
2624
+ * current one (`artifact-ownership-and-delivery-plan.md` → D28).
2625
+ *
2626
+ * **It is still delivered, and that is deliberate.** Dropping the item from
2627
+ * the response would say the same thing more quietly and cost two things
2628
+ * worth more than the byte: the publishing repo would lose the id it needs to
2629
+ * republish the path in place — re-adding a deleted file would create a
2630
+ * second artifact at the same path rather than a new revision of the one
2631
+ * that is there — and a reader would be left unable to tell a removal from
2632
+ * a bundle it has stopped being able to see. What the flag asks of a client
2633
+ * is one thing: do not materialize it. A file left at a discovery root keeps
2634
+ * feeding deleted guidance into every agent that reads that repo, which is
2635
+ * the failure the decision exists to stop.
2636
+ *
2637
+ * **Optional, and absent means an ordinary artifact.** A client that has
2638
+ * never heard of it behaves as it always did — it keeps the last published
2639
+ * revision on disk, which is the retain behaviour this replaces rather than a
2640
+ * new failure. That is what makes the server safe to ship first.
2641
+ *
2642
+ * `literal(true)` rather than a boolean: `removed: false` would be a second
2643
+ * spelling of absence, and an artifact that came back is content again rather
2644
+ * than a tombstone that says no.
2645
+ */
2646
+ readonly removed: v.OptionalSchema<v.LiteralSchema<true, undefined>, undefined>;
1182
2647
  }, undefined>;
1183
2648
  }, undefined>;
1184
2649
  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">]>;
@@ -1197,7 +2662,8 @@ export declare const InboxCaptureRequestSchema: v.ObjectSchema<{
1197
2662
  * from it. The one in-repo caller is the dashboard composer.)
1198
2663
  */
1199
2664
  readonly id: v.OptionalSchema<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">]>, undefined>;
1200
- readonly contentType: v.PicklistSchema<("document" | "reference" | "asset")[], undefined>;
2665
+ readonly bundleId: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
2666
+ readonly contentType: v.PicklistSchema<("content" | "asset")[], undefined>;
1201
2667
  readonly content: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.CheckAction<string, "content must be at most 262144 bytes">]>;
1202
2668
  readonly name: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 200, undefined>]>, undefined>;
1203
2669
  readonly source: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
@@ -1206,7 +2672,9 @@ export declare const InboxItemSchema: v.ObjectSchema<{
1206
2672
  readonly id: v.StringSchema<undefined>;
1207
2673
  readonly type: v.PicklistSchema<string[], undefined>;
1208
2674
  readonly name: v.StringSchema<undefined>;
1209
- readonly contentType: v.StringSchema<undefined>;
2675
+ /** The stored pair, as {@link ContextItemSchema} carries it. */
2676
+ readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
2677
+ readonly format: v.NullableSchema<v.StringSchema<undefined>, undefined>;
1210
2678
  readonly content: v.NullableSchema<v.StringSchema<undefined>, undefined>;
1211
2679
  readonly source: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
1212
2680
  readonly version: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
@@ -1218,7 +2686,9 @@ export declare const InboxCaptureResponseSchema: v.ObjectSchema<{
1218
2686
  readonly id: v.StringSchema<undefined>;
1219
2687
  readonly type: v.PicklistSchema<string[], undefined>;
1220
2688
  readonly name: v.StringSchema<undefined>;
1221
- readonly contentType: v.StringSchema<undefined>;
2689
+ /** The stored pair, as {@link ContextItemSchema} carries it. */
2690
+ readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
2691
+ readonly format: v.NullableSchema<v.StringSchema<undefined>, undefined>;
1222
2692
  readonly content: v.NullableSchema<v.StringSchema<undefined>, undefined>;
1223
2693
  readonly source: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
1224
2694
  readonly version: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
@@ -1231,7 +2701,9 @@ export declare const InboxListResponseSchema: v.ObjectSchema<{
1231
2701
  readonly id: v.StringSchema<undefined>;
1232
2702
  readonly type: v.PicklistSchema<string[], undefined>;
1233
2703
  readonly name: v.StringSchema<undefined>;
1234
- readonly contentType: v.StringSchema<undefined>;
2704
+ /** The stored pair, as {@link ContextItemSchema} carries it. */
2705
+ readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
2706
+ readonly format: v.NullableSchema<v.StringSchema<undefined>, undefined>;
1235
2707
  readonly content: v.NullableSchema<v.StringSchema<undefined>, undefined>;
1236
2708
  readonly source: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
1237
2709
  readonly version: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
@@ -1565,7 +3037,7 @@ export declare const MAX_SYNC_AUX_BATCH = 100;
1565
3037
  */
1566
3038
  export declare const MAX_RULE_MANIFEST_FILES = 500;
1567
3039
  /**
1568
- * A rule file observed on disk in the repo `mossbear sync` ran from.
3040
+ * A rule file observed on disk in the repo `mossbear report` ran from.
1569
3041
  *
1570
3042
  * `path` is relative to that repo root, in exactly the form `payloadPath`
1571
3043
  * takes at import time (`packages/cli/src/rules/discover.ts`), so
@@ -1708,18 +3180,18 @@ export type SessionSelfReport = v.InferOutput<typeof SessionSelfReportSchema>;
1708
3180
  /**
1709
3181
  * The CLI entry point a sync came from, when that entry point is a hook.
1710
3182
  *
1711
- * **One member on purpose.** `mossbear session-start` is the command
3183
+ * **One member on purpose.** `mossbear refresh` is the command
1712
3184
  * `mossbear init` registers as the `SessionStart` hook, and nothing else runs
1713
3185
  * it — so a request carrying this value is proof that the hooks a project was
1714
3186
  * set up with are firing, which is the one onboarding fact the dashboard could
1715
3187
  * not previously observe. The other two hooks (`Stop`, `SessionEnd`) both run
1716
- * `mossbear sync`, which is also the command a person types by hand; their
3188
+ * `mossbear report`, which is also the command a person types by hand; their
1717
3189
  * requests are therefore indistinguishable from a manual sync and are
1718
3190
  * deliberately not named here rather than guessed at.
1719
3191
  *
1720
3192
  * Optional on the envelope, and its absence means only "not known to be a
1721
3193
  * session-start sync" — never "no hooks". A CLI predating this field sends
1722
- * none, and so does every ordinary `mossbear sync`.
3194
+ * none, and so does every ordinary `mossbear report`.
1723
3195
  *
1724
3196
  * A user can pass the flag that sets this by hand. That is not a privilege
1725
3197
  * boundary: the value is scoped to the caller's own account and the only thing
@@ -1911,12 +3383,12 @@ export declare const DashboardSyncRequestSchema: v.ObjectSchema<{
1911
3383
  readonly cliVersion: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.NonEmptyAction<string, undefined>, v.MaxLengthAction<string, 64, undefined>]>, undefined>;
1912
3384
  /**
1913
3385
  * Sessions whose agent context has ended, named by the CLI's `SessionEnd`
1914
- * hook (`mossbear sync --session-complete`) — never by its per-turn `Stop` hook.
3386
+ * hook (`mossbear complete`) — never by its per-turn `Stop` hook.
1915
3387
  * The server closes those sessions' runs; every other session in the payload
1916
3388
  * stays open.
1917
3389
  *
1918
3390
  * Session-keyed rather than a single envelope-level boolean, because one
1919
- * `mossbear sync` uploads every session with pending actions and chunks them
3391
+ * `mossbear report` uploads every session with pending actions and chunks them
1920
3392
  * across several requests. A boolean would close sessions that merely had a
1921
3393
  * backlog, and would close a session before the batches carrying the rest of
1922
3394
  * its actions had arrived. The CLI therefore names a session here only on the
@@ -2111,7 +3583,7 @@ export declare const ActionEntrySchema: v.ObjectSchema<{
2111
3583
  * This is what makes a skill load ride the action stream instead of the
2112
3584
  * transcript. `skill_usage` — the other place a loaded skill name is
2113
3585
  * recorded — is populated by `extractSessionUsage`, which returns empty unless
2114
- * `mossbear sync` is given `--transcripts-dir`, and the hook `mossbear init`
3586
+ * `mossbear report` is given `--transcripts-dir`, and the hook `mossbear init`
2115
3587
  * installs never passes one. So the transcript path has no data in a normal
2116
3588
  * session, while an action definitionally syncs.
2117
3589
  */
@@ -2127,7 +3599,7 @@ export declare const ActionEntrySchema: v.ObjectSchema<{
2127
3599
  * (`packages/cli/src/action-queue.ts`) builds the wire payload field by
2128
3600
  * field and does not include this one; transcripts are disclosed as
2129
3601
  * local-only in the dashboard's own privacy disclosure, and a path is still
2130
- * a fact about the user's filesystem. It exists so `mossbear sync` can find
3602
+ * a fact about the user's filesystem. It exists so `mossbear report` can find
2131
3603
  * the transcript for a session it is already uploading without searching for
2132
3604
  * it.
2133
3605
  *
@@ -2542,20 +4014,6 @@ export declare const GuideHistoryGuideSchema: v.ObjectSchema<{
2542
4014
  readonly path: 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>;
2543
4015
  readonly root: v.NullableSchema<v.PicklistSchema<["project", "global"], undefined>, undefined>;
2544
4016
  }, undefined>;
2545
- /**
2546
- * The markers every `reasoning` block in this response is wrapped in, plus a
2547
- * statement of what they mean.
2548
- *
2549
- * Generated per response from the content itself, so no marker-like text inside
2550
- * a block can end it early — a property `deriveDelimiterToken` checks rather
2551
- * than assumes.
2552
- */
2553
- export declare const GuideHistoryUntrustedSchema: v.ObjectSchema<{
2554
- readonly token: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
2555
- readonly startMarker: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
2556
- readonly endMarker: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
2557
- readonly note: v.StringSchema<undefined>;
2558
- }, undefined>;
2559
4017
  export declare const GuideHistoryResponseSchema: v.ObjectSchema<{
2560
4018
  readonly guide: v.ObjectSchema<{
2561
4019
  readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
@@ -2849,77 +4307,6 @@ export declare const SessionGradeResponseSchema: v.ObjectSchema<{
2849
4307
  }, undefined>, undefined>;
2850
4308
  }, undefined>;
2851
4309
  export type SessionGradeResponse = v.InferOutput<typeof SessionGradeResponseSchema>;
2852
- /**
2853
- * The five kinds of session residue the server used to extract on session
2854
- * close. No longer produced by anything — kept so an already-installed CLI's
2855
- * parse of the (now always-empty) response still type-checks against the
2856
- * same shape it always has.
2857
- */
2858
- export declare const SessionResidueKindSchema: v.PicklistSchema<["decision", "deferral", "assumption", "question", "found_not_fixed"], undefined>;
2859
- export type SessionResidueKind = v.InferOutput<typeof SessionResidueKindSchema>;
2860
- /**
2861
- * How many residue items one read returns at most — the same cap the
2862
- * extractor applies per session, applied again across sessions: the handoff a
2863
- * session reads at start is a glance, not a log.
2864
- */
2865
- export declare const MAX_SESSION_RESIDUE_ITEMS = 5;
2866
- /** `?project=` — the committed project id whose recent sessions to read. */
2867
- export declare const SessionResidueRequestSchema: v.ObjectSchema<{
2868
- readonly project: 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">]>;
2869
- }, undefined>;
2870
- export type SessionResidueRequest = v.InferOutput<typeof SessionResidueRequestSchema>;
2871
- /** One item a recent session in the project left behind. */
2872
- export declare const SessionResidueItemSchema: v.ObjectSchema<{
2873
- readonly kind: v.PicklistSchema<["decision", "deferral", "assumption", "question", "found_not_fixed"], undefined>;
2874
- /**
2875
- * The item's text, **already wrapped in the response's untrusted markers**
2876
- * — model-authored, transcript-derived, and about to be placed in front of
2877
- * an agent, so delimited at the source exactly as a grade's reasoning is.
2878
- */
2879
- readonly text: v.StringSchema<undefined>;
2880
- /** The run the item came from; what `mossbear sessions <id>` takes. */
2881
- readonly sessionId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
2882
- readonly agentSessionId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
2883
- /** ISO timestamp of the session's close; null while it is still open. */
2884
- readonly endedAt: v.NullableSchema<v.StringSchema<undefined>, undefined>;
2885
- }, undefined>;
2886
- export type SessionResidueItem = v.InferOutput<typeof SessionResidueItemSchema>;
2887
- export declare const SessionResidueResponseSchema: v.ObjectSchema<{
2888
- readonly project: 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">]>;
2889
- /**
2890
- * Newest session first, then in the order the session recorded them; at
2891
- * most {@link MAX_SESSION_RESIDUE_ITEMS}. Empty is the ordinary answer and
2892
- * says "nothing on record", never "nothing happened".
2893
- */
2894
- readonly items: v.SchemaWithPipe<readonly [v.ArraySchema<v.ObjectSchema<{
2895
- readonly kind: v.PicklistSchema<["decision", "deferral", "assumption", "question", "found_not_fixed"], undefined>;
2896
- /**
2897
- * The item's text, **already wrapped in the response's untrusted markers**
2898
- * — model-authored, transcript-derived, and about to be placed in front of
2899
- * an agent, so delimited at the source exactly as a grade's reasoning is.
2900
- */
2901
- readonly text: v.StringSchema<undefined>;
2902
- /** The run the item came from; what `mossbear sessions <id>` takes. */
2903
- readonly sessionId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
2904
- readonly agentSessionId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
2905
- /** ISO timestamp of the session's close; null while it is still open. */
2906
- readonly endedAt: v.NullableSchema<v.StringSchema<undefined>, undefined>;
2907
- }, undefined>, undefined>, v.MaxLengthAction<{
2908
- kind: "decision" | "deferral" | "assumption" | "question" | "found_not_fixed";
2909
- text: string;
2910
- sessionId: string;
2911
- agentSessionId: string;
2912
- endedAt: string | null;
2913
- }[], 5, undefined>]>;
2914
- /** The markers every `text` is wrapped in; present exactly when `items` is non-empty. */
2915
- readonly untrusted: v.NullableSchema<v.ObjectSchema<{
2916
- readonly token: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
2917
- readonly startMarker: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
2918
- readonly endMarker: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
2919
- readonly note: v.StringSchema<undefined>;
2920
- }, undefined>, undefined>;
2921
- }, undefined>;
2922
- export type SessionResidueResponse = v.InferOutput<typeof SessionResidueResponseSchema>;
2923
4310
  export declare function parseAgentConfig(data: unknown): {
2924
4311
  id: string;
2925
4312
  name: string;
@@ -3086,7 +4473,8 @@ export declare function parseContextItem(data: unknown): {
3086
4473
  id: string;
3087
4474
  type: string;
3088
4475
  name: string;
3089
- contentType: string;
4476
+ role: string | null;
4477
+ format: string | null;
3090
4478
  content: string | null;
3091
4479
  origin?: string | null | undefined;
3092
4480
  version?: number | undefined;
@@ -3098,14 +4486,32 @@ export declare function parseContextItem(data: unknown): {
3098
4486
  root: "project" | "global";
3099
4487
  path: string;
3100
4488
  }[] | undefined;
4489
+ notes?: {
4490
+ id: string;
4491
+ body: string;
4492
+ authorName: string | null;
4493
+ createdAt: string;
4494
+ itemVersion: number;
4495
+ itemChangedSince: boolean;
4496
+ deliveredCount: number;
4497
+ threadId: string;
4498
+ replyToId: string | null;
4499
+ }[] | undefined;
3101
4500
  updatedAt: string;
4501
+ gitSource?: {
4502
+ projectId: string;
4503
+ commitSha: string;
4504
+ branch?: string | undefined;
4505
+ } | null | undefined;
4506
+ removed?: true | undefined;
3102
4507
  };
3103
4508
  export declare function parseContextItemsResponse(data: unknown): {
3104
4509
  items: {
3105
4510
  id: string;
3106
4511
  type: string;
3107
4512
  name: string;
3108
- contentType: string;
4513
+ role: string | null;
4514
+ format: string | null;
3109
4515
  content: string | null;
3110
4516
  origin?: string | null | undefined;
3111
4517
  version?: number | undefined;
@@ -3117,25 +4523,54 @@ export declare function parseContextItemsResponse(data: unknown): {
3117
4523
  root: "project" | "global";
3118
4524
  path: string;
3119
4525
  }[] | undefined;
4526
+ notes?: {
4527
+ id: string;
4528
+ body: string;
4529
+ authorName: string | null;
4530
+ createdAt: string;
4531
+ itemVersion: number;
4532
+ itemChangedSince: boolean;
4533
+ deliveredCount: number;
4534
+ threadId: string;
4535
+ replyToId: string | null;
4536
+ }[] | undefined;
3120
4537
  updatedAt: string;
4538
+ gitSource?: {
4539
+ projectId: string;
4540
+ commitSha: string;
4541
+ branch?: string | undefined;
4542
+ } | null | undefined;
4543
+ removed?: true | undefined;
3121
4544
  }[];
4545
+ untrusted?: {
4546
+ token: string;
4547
+ startMarker: string;
4548
+ endMarker: string;
4549
+ note: string;
4550
+ } | null | undefined;
3122
4551
  };
3123
4552
  export declare function parsePushContextRequest(data: unknown): {
3124
4553
  name: string;
3125
- contentType: "document" | "reference" | "asset";
4554
+ contentType: "content" | "asset";
3126
4555
  content: string;
3127
4556
  itemId?: string | undefined;
3128
4557
  origin?: string | null | undefined;
3129
4558
  sourceItemIds?: string[] | undefined;
3130
4559
  path?: string | null | undefined;
3131
4560
  projectId?: string | undefined;
4561
+ gitSource?: {
4562
+ projectId: string;
4563
+ commitSha: string;
4564
+ branch?: string | undefined;
4565
+ } | undefined;
3132
4566
  };
3133
4567
  export declare function parsePushContextResponse(data: unknown): {
3134
4568
  item: {
3135
4569
  id: string;
3136
4570
  type: string;
3137
4571
  name: string;
3138
- contentType: string;
4572
+ role: string | null;
4573
+ format: string | null;
3139
4574
  content: string | null;
3140
4575
  origin?: string | null | undefined;
3141
4576
  version?: number | undefined;
@@ -3147,7 +4582,24 @@ export declare function parsePushContextResponse(data: unknown): {
3147
4582
  root: "project" | "global";
3148
4583
  path: string;
3149
4584
  }[] | undefined;
4585
+ notes?: {
4586
+ id: string;
4587
+ body: string;
4588
+ authorName: string | null;
4589
+ createdAt: string;
4590
+ itemVersion: number;
4591
+ itemChangedSince: boolean;
4592
+ deliveredCount: number;
4593
+ threadId: string;
4594
+ replyToId: string | null;
4595
+ }[] | undefined;
3150
4596
  updatedAt: string;
4597
+ gitSource?: {
4598
+ projectId: string;
4599
+ commitSha: string;
4600
+ branch?: string | undefined;
4601
+ } | null | undefined;
4602
+ removed?: true | undefined;
3151
4603
  };
3152
4604
  created: boolean;
3153
4605
  };
@@ -3158,13 +4610,20 @@ export declare function parseUpdateContextItemRequest(data: unknown): {
3158
4610
  expectedVersion?: number | undefined;
3159
4611
  projectId?: string | undefined;
3160
4612
  sourceItemIds?: string[] | undefined;
4613
+ gitSource?: {
4614
+ projectId: string;
4615
+ commitSha: string;
4616
+ branch?: string | undefined;
4617
+ } | undefined;
4618
+ removed?: true | undefined;
3161
4619
  };
3162
4620
  export declare function parseUpdateContextItemResponse(data: unknown): {
3163
4621
  item: {
3164
4622
  id: string;
3165
4623
  type: string;
3166
4624
  name: string;
3167
- contentType: string;
4625
+ role: string | null;
4626
+ format: string | null;
3168
4627
  content: string | null;
3169
4628
  origin?: string | null | undefined;
3170
4629
  version?: number | undefined;
@@ -3176,7 +4635,24 @@ export declare function parseUpdateContextItemResponse(data: unknown): {
3176
4635
  root: "project" | "global";
3177
4636
  path: string;
3178
4637
  }[] | undefined;
4638
+ notes?: {
4639
+ id: string;
4640
+ body: string;
4641
+ authorName: string | null;
4642
+ createdAt: string;
4643
+ itemVersion: number;
4644
+ itemChangedSince: boolean;
4645
+ deliveredCount: number;
4646
+ threadId: string;
4647
+ replyToId: string | null;
4648
+ }[] | undefined;
3179
4649
  updatedAt: string;
4650
+ gitSource?: {
4651
+ projectId: string;
4652
+ commitSha: string;
4653
+ branch?: string | undefined;
4654
+ } | null | undefined;
4655
+ removed?: true | undefined;
3180
4656
  };
3181
4657
  updated: boolean;
3182
4658
  };
@@ -3185,6 +4661,12 @@ export declare function parseUpdateContextItemBody(data: unknown): {
3185
4661
  content?: string | undefined;
3186
4662
  expectedVersion?: number | undefined;
3187
4663
  projectId?: string | undefined;
4664
+ gitSource?: {
4665
+ projectId: string;
4666
+ commitSha: string;
4667
+ branch?: string | undefined;
4668
+ } | undefined;
4669
+ removed?: true | undefined;
3188
4670
  sourceItemIds?: string[] | undefined;
3189
4671
  };
3190
4672
  export declare function parseContextItemResponse(data: unknown): {
@@ -3192,7 +4674,8 @@ export declare function parseContextItemResponse(data: unknown): {
3192
4674
  id: string;
3193
4675
  type: string;
3194
4676
  name: string;
3195
- contentType: string;
4677
+ role: string | null;
4678
+ format: string | null;
3196
4679
  content: string | null;
3197
4680
  origin?: string | null | undefined;
3198
4681
  version?: number | undefined;
@@ -3204,7 +4687,24 @@ export declare function parseContextItemResponse(data: unknown): {
3204
4687
  root: "project" | "global";
3205
4688
  path: string;
3206
4689
  }[] | undefined;
4690
+ notes?: {
4691
+ id: string;
4692
+ body: string;
4693
+ authorName: string | null;
4694
+ createdAt: string;
4695
+ itemVersion: number;
4696
+ itemChangedSince: boolean;
4697
+ deliveredCount: number;
4698
+ threadId: string;
4699
+ replyToId: string | null;
4700
+ }[] | undefined;
3207
4701
  updatedAt: string;
4702
+ gitSource?: {
4703
+ projectId: string;
4704
+ commitSha: string;
4705
+ branch?: string | undefined;
4706
+ } | null | undefined;
4707
+ removed?: true | undefined;
3208
4708
  };
3209
4709
  };
3210
4710
  export declare function parseArchiveContextItemResponse(data: unknown): {
@@ -3213,7 +4713,8 @@ export declare function parseArchiveContextItemResponse(data: unknown): {
3213
4713
  id: string;
3214
4714
  type: string;
3215
4715
  name: string;
3216
- contentType: string;
4716
+ role: string | null;
4717
+ format: string | null;
3217
4718
  content: string | null;
3218
4719
  origin?: string | null | undefined;
3219
4720
  version?: number | undefined;
@@ -3225,12 +4726,30 @@ export declare function parseArchiveContextItemResponse(data: unknown): {
3225
4726
  root: "project" | "global";
3226
4727
  path: string;
3227
4728
  }[] | undefined;
4729
+ notes?: {
4730
+ id: string;
4731
+ body: string;
4732
+ authorName: string | null;
4733
+ createdAt: string;
4734
+ itemVersion: number;
4735
+ itemChangedSince: boolean;
4736
+ deliveredCount: number;
4737
+ threadId: string;
4738
+ replyToId: string | null;
4739
+ }[] | undefined;
3228
4740
  updatedAt: string;
4741
+ gitSource?: {
4742
+ projectId: string;
4743
+ commitSha: string;
4744
+ branch?: string | undefined;
4745
+ } | null | undefined;
4746
+ removed?: true | undefined;
3229
4747
  };
3230
4748
  };
3231
4749
  export declare function parseInboxCaptureRequest(data: unknown): {
3232
4750
  id?: string | undefined;
3233
- contentType: "document" | "reference" | "asset";
4751
+ bundleId?: string | null | undefined;
4752
+ contentType: "content" | "asset";
3234
4753
  content: string;
3235
4754
  name?: string | undefined;
3236
4755
  source?: string | undefined;
@@ -3240,7 +4759,8 @@ export declare function parseInboxCaptureResponse(data: unknown): {
3240
4759
  id: string;
3241
4760
  type: string;
3242
4761
  name: string;
3243
- contentType: string;
4762
+ role: string | null;
4763
+ format: string | null;
3244
4764
  content: string | null;
3245
4765
  source?: string | null | undefined;
3246
4766
  version?: number | undefined;
@@ -3253,7 +4773,8 @@ export declare function parseInboxListResponse(data: unknown): {
3253
4773
  id: string;
3254
4774
  type: string;
3255
4775
  name: string;
3256
- contentType: string;
4776
+ role: string | null;
4777
+ format: string | null;
3257
4778
  content: string | null;
3258
4779
  source?: string | null | undefined;
3259
4780
  version?: number | undefined;
@@ -3546,6 +5067,35 @@ export declare function parseGuideHistoryResponse(data: unknown): {
3546
5067
  note: string;
3547
5068
  };
3548
5069
  };
5070
+ export declare function parseAnnounceItemNotesRequest(data: unknown): {
5071
+ projectId: string;
5072
+ bundleIds: string[];
5073
+ };
5074
+ export declare function parseAnnounceItemNotesResponse(data: unknown): {
5075
+ open: number;
5076
+ announced: number;
5077
+ };
5078
+ export declare function parseItemNotesResponse(data: unknown): {
5079
+ notes: {
5080
+ itemName: string;
5081
+ itemPath: string | null;
5082
+ id: string;
5083
+ body: string;
5084
+ authorName: string | null;
5085
+ createdAt: string;
5086
+ itemVersion: number;
5087
+ itemChangedSince: boolean;
5088
+ deliveredCount: number;
5089
+ threadId: string;
5090
+ replyToId: string | null;
5091
+ }[];
5092
+ untrusted?: {
5093
+ token: string;
5094
+ startMarker: string;
5095
+ endMarker: string;
5096
+ note: string;
5097
+ } | null | undefined;
5098
+ };
3549
5099
  export declare function parseRunGradeRequest(data: unknown): {
3550
5100
  session?: string | undefined;
3551
5101
  agent_session?: string | undefined;
@@ -3578,21 +5128,5 @@ export declare function parseSessionGradeResponse(data: unknown): {
3578
5128
  note: string;
3579
5129
  } | null;
3580
5130
  };
3581
- export declare function parseSessionResidueResponse(data: unknown): {
3582
- project: string;
3583
- items: {
3584
- kind: "decision" | "deferral" | "assumption" | "question" | "found_not_fixed";
3585
- text: string;
3586
- sessionId: string;
3587
- agentSessionId: string;
3588
- endedAt: string | null;
3589
- }[];
3590
- untrusted: {
3591
- token: string;
3592
- startMarker: string;
3593
- endMarker: string;
3594
- note: string;
3595
- } | null;
3596
- };
3597
5131
  export {};
3598
5132
  //# sourceMappingURL=schemas.d.ts.map