@mossbear/protocol 0.1.0-alpha.53 → 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
  /**
@@ -939,11 +948,72 @@ export declare const ContextItemNoteSchema: v.ObjectSchema<{
939
948
  readonly replyToId: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, undefined>;
940
949
  }, undefined>;
941
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>;
942
997
  export declare const ContextItemSchema: v.ObjectSchema<{
943
998
  readonly id: v.StringSchema<undefined>;
944
999
  readonly type: v.PicklistSchema<string[], undefined>;
945
1000
  readonly name: v.StringSchema<undefined>;
946
- 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>;
947
1017
  readonly content: v.NullableSchema<v.StringSchema<undefined>, undefined>;
948
1018
  readonly origin: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
949
1019
  readonly version: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
@@ -1037,13 +1107,95 @@ export declare const ContextItemSchema: v.ObjectSchema<{
1037
1107
  replyToId: string | null;
1038
1108
  }[], 20, undefined>]>, undefined>;
1039
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>;
1040
1177
  }, undefined>;
1041
1178
  export declare const ContextItemsResponseSchema: v.ObjectSchema<{
1042
1179
  readonly items: v.ArraySchema<v.ObjectSchema<{
1043
1180
  readonly id: v.StringSchema<undefined>;
1044
1181
  readonly type: v.PicklistSchema<string[], undefined>;
1045
1182
  readonly name: v.StringSchema<undefined>;
1046
- 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>;
1047
1199
  readonly content: v.NullableSchema<v.StringSchema<undefined>, undefined>;
1048
1200
  readonly origin: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
1049
1201
  readonly version: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
@@ -1137,6 +1289,73 @@ export declare const ContextItemsResponseSchema: v.ObjectSchema<{
1137
1289
  replyToId: string | null;
1138
1290
  }[], 20, undefined>]>, undefined>;
1139
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>;
1140
1359
  }, undefined>, undefined>;
1141
1360
  /**
1142
1361
  * The markers every note `body` in this response is wrapped in, plus a
@@ -1150,6 +1369,213 @@ export declare const ContextItemsResponseSchema: v.ObjectSchema<{
1150
1369
  readonly note: v.StringSchema<undefined>;
1151
1370
  }, undefined>, undefined>, undefined>;
1152
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>]>;
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>;
1153
1579
  /** Max number of context item ids a push may cite as its transform sources. */
1154
1580
  export declare const MAX_TRANSFORM_SOURCE_IDS = 100;
1155
1581
  /**
@@ -1162,7 +1588,7 @@ export declare const SourceItemIdsSchema: v.SchemaWithPipe<readonly [v.ArraySche
1162
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>]>;
1163
1589
  export declare const PushContextRequestSchema: v.ObjectSchema<{
1164
1590
  readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 200, undefined>]>;
1165
- readonly contentType: v.PicklistSchema<("document" | "reference" | "asset")[], undefined>;
1591
+ readonly contentType: v.PicklistSchema<("content" | "asset")[], undefined>;
1166
1592
  readonly content: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.CheckAction<string, "content must be at most 262144 bytes">]>;
1167
1593
  readonly itemId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
1168
1594
  readonly origin: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
@@ -1180,13 +1606,65 @@ export declare const PushContextRequestSchema: v.ObjectSchema<{
1180
1606
  * a member of the bundle's workspace to reach this route at all.
1181
1607
  */
1182
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>;
1183
1646
  }, undefined>;
1184
1647
  export declare const PushContextResponseSchema: v.ObjectSchema<{
1185
1648
  readonly item: v.ObjectSchema<{
1186
1649
  readonly id: v.StringSchema<undefined>;
1187
1650
  readonly type: v.PicklistSchema<string[], undefined>;
1188
1651
  readonly name: v.StringSchema<undefined>;
1189
- 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>;
1190
1668
  readonly content: v.NullableSchema<v.StringSchema<undefined>, undefined>;
1191
1669
  readonly origin: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
1192
1670
  readonly version: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
@@ -1280,6 +1758,73 @@ export declare const PushContextResponseSchema: v.ObjectSchema<{
1280
1758
  replyToId: string | null;
1281
1759
  }[], 20, undefined>]>, undefined>;
1282
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>;
1283
1828
  }, undefined>;
1284
1829
  readonly created: v.BooleanSchema<undefined>;
1285
1830
  }, undefined>;
@@ -1296,13 +1841,80 @@ export declare const UpdateContextItemRequestSchema: v.ObjectSchema<{
1296
1841
  */
1297
1842
  readonly projectId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
1298
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>;
1299
1896
  }, undefined>;
1300
1897
  export declare const UpdateContextItemResponseSchema: v.ObjectSchema<{
1301
1898
  readonly item: v.ObjectSchema<{
1302
1899
  readonly id: v.StringSchema<undefined>;
1303
1900
  readonly type: v.PicklistSchema<string[], undefined>;
1304
1901
  readonly name: v.StringSchema<undefined>;
1305
- 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>;
1306
1918
  readonly content: v.NullableSchema<v.StringSchema<undefined>, undefined>;
1307
1919
  readonly origin: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
1308
1920
  readonly version: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
@@ -1396,6 +2008,73 @@ export declare const UpdateContextItemResponseSchema: v.ObjectSchema<{
1396
2008
  replyToId: string | null;
1397
2009
  }[], 20, undefined>]>, undefined>;
1398
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>;
1399
2078
  }, undefined>;
1400
2079
  readonly updated: v.BooleanSchema<undefined>;
1401
2080
  }, undefined>;
@@ -1412,6 +2091,58 @@ export declare const UpdateContextItemBodySchema: Omit<v.ObjectSchema<{
1412
2091
  */
1413
2092
  readonly projectId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
1414
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>;
1415
2146
  }, undefined>, "entries" | "~types" | "~run" | "~standard"> & {
1416
2147
  readonly entries: Omit<{
1417
2148
  readonly itemId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
@@ -1426,18 +2157,82 @@ export declare const UpdateContextItemBodySchema: Omit<v.ObjectSchema<{
1426
2157
  */
1427
2158
  readonly projectId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
1428
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>;
1429
2212
  }, "itemId">;
1430
2213
  readonly "~standard": v.StandardProps<{
1431
2214
  name?: string | undefined;
1432
2215
  content?: string | undefined;
1433
2216
  expectedVersion?: number | undefined;
1434
2217
  projectId?: string | undefined;
2218
+ gitSource?: {
2219
+ projectId: string;
2220
+ commitSha: string;
2221
+ branch?: string | undefined;
2222
+ } | undefined;
2223
+ removed?: true | undefined;
1435
2224
  sourceItemIds?: string[] | undefined;
1436
2225
  }, {
1437
2226
  name?: string | undefined;
1438
2227
  content?: string | undefined;
1439
2228
  expectedVersion?: number | undefined;
1440
2229
  projectId?: string | undefined;
2230
+ gitSource?: {
2231
+ projectId: string;
2232
+ commitSha: string;
2233
+ branch?: string | undefined;
2234
+ } | undefined;
2235
+ removed?: true | undefined;
1441
2236
  sourceItemIds?: string[] | undefined;
1442
2237
  }>;
1443
2238
  readonly "~run": (dataset: v.UnknownDataset, config: v.Config<v.BaseIssue<unknown>>) => v.OutputDataset<{
@@ -1445,14 +2240,26 @@ export declare const UpdateContextItemBodySchema: Omit<v.ObjectSchema<{
1445
2240
  content?: string | undefined;
1446
2241
  expectedVersion?: number | undefined;
1447
2242
  projectId?: string | undefined;
2243
+ gitSource?: {
2244
+ projectId: string;
2245
+ commitSha: string;
2246
+ branch?: string | undefined;
2247
+ } | undefined;
2248
+ removed?: true | undefined;
1448
2249
  sourceItemIds?: string[] | undefined;
1449
- }, 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>>;
1450
2251
  readonly "~types"?: {
1451
2252
  readonly input: {
1452
2253
  name?: string | undefined;
1453
2254
  content?: string | undefined;
1454
2255
  expectedVersion?: number | undefined;
1455
2256
  projectId?: string | undefined;
2257
+ gitSource?: {
2258
+ projectId: string;
2259
+ commitSha: string;
2260
+ branch?: string | undefined;
2261
+ } | undefined;
2262
+ removed?: true | undefined;
1456
2263
  sourceItemIds?: string[] | undefined;
1457
2264
  };
1458
2265
  readonly output: {
@@ -1460,9 +2267,15 @@ export declare const UpdateContextItemBodySchema: Omit<v.ObjectSchema<{
1460
2267
  content?: string | undefined;
1461
2268
  expectedVersion?: number | undefined;
1462
2269
  projectId?: string | undefined;
2270
+ gitSource?: {
2271
+ projectId: string;
2272
+ commitSha: string;
2273
+ branch?: string | undefined;
2274
+ } | undefined;
2275
+ removed?: true | undefined;
1463
2276
  sourceItemIds?: string[] | undefined;
1464
2277
  };
1465
- 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>;
1466
2279
  } | undefined;
1467
2280
  };
1468
2281
  /** A single canonical item, for the item-scoped read route. */
@@ -1471,7 +2284,22 @@ export declare const ContextItemResponseSchema: v.ObjectSchema<{
1471
2284
  readonly id: v.StringSchema<undefined>;
1472
2285
  readonly type: v.PicklistSchema<string[], undefined>;
1473
2286
  readonly name: v.StringSchema<undefined>;
1474
- 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>;
1475
2303
  readonly content: v.NullableSchema<v.StringSchema<undefined>, undefined>;
1476
2304
  readonly origin: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
1477
2305
  readonly version: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
@@ -1565,6 +2393,73 @@ export declare const ContextItemResponseSchema: v.ObjectSchema<{
1565
2393
  replyToId: string | null;
1566
2394
  }[], 20, undefined>]>, undefined>;
1567
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>;
1568
2463
  }, undefined>;
1569
2464
  }, undefined>;
1570
2465
  export declare const ArchiveContextItemResponseSchema: v.ObjectSchema<{
@@ -1573,7 +2468,22 @@ export declare const ArchiveContextItemResponseSchema: v.ObjectSchema<{
1573
2468
  readonly id: v.StringSchema<undefined>;
1574
2469
  readonly type: v.PicklistSchema<string[], undefined>;
1575
2470
  readonly name: v.StringSchema<undefined>;
1576
- 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>;
1577
2487
  readonly content: v.NullableSchema<v.StringSchema<undefined>, undefined>;
1578
2488
  readonly origin: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
1579
2489
  readonly version: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
@@ -1667,6 +2577,73 @@ export declare const ArchiveContextItemResponseSchema: v.ObjectSchema<{
1667
2577
  replyToId: string | null;
1668
2578
  }[], 20, undefined>]>, undefined>;
1669
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>;
1670
2647
  }, undefined>;
1671
2648
  }, undefined>;
1672
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">]>;
@@ -1686,7 +2663,7 @@ export declare const InboxCaptureRequestSchema: v.ObjectSchema<{
1686
2663
  */
1687
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>;
1688
2665
  readonly bundleId: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
1689
- readonly contentType: v.PicklistSchema<("document" | "reference" | "asset")[], undefined>;
2666
+ readonly contentType: v.PicklistSchema<("content" | "asset")[], undefined>;
1690
2667
  readonly content: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.CheckAction<string, "content must be at most 262144 bytes">]>;
1691
2668
  readonly name: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 200, undefined>]>, undefined>;
1692
2669
  readonly source: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
@@ -1695,7 +2672,9 @@ export declare const InboxItemSchema: v.ObjectSchema<{
1695
2672
  readonly id: v.StringSchema<undefined>;
1696
2673
  readonly type: v.PicklistSchema<string[], undefined>;
1697
2674
  readonly name: v.StringSchema<undefined>;
1698
- 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>;
1699
2678
  readonly content: v.NullableSchema<v.StringSchema<undefined>, undefined>;
1700
2679
  readonly source: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
1701
2680
  readonly version: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
@@ -1707,7 +2686,9 @@ export declare const InboxCaptureResponseSchema: v.ObjectSchema<{
1707
2686
  readonly id: v.StringSchema<undefined>;
1708
2687
  readonly type: v.PicklistSchema<string[], undefined>;
1709
2688
  readonly name: v.StringSchema<undefined>;
1710
- 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>;
1711
2692
  readonly content: v.NullableSchema<v.StringSchema<undefined>, undefined>;
1712
2693
  readonly source: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
1713
2694
  readonly version: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
@@ -1720,7 +2701,9 @@ export declare const InboxListResponseSchema: v.ObjectSchema<{
1720
2701
  readonly id: v.StringSchema<undefined>;
1721
2702
  readonly type: v.PicklistSchema<string[], undefined>;
1722
2703
  readonly name: v.StringSchema<undefined>;
1723
- 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>;
1724
2707
  readonly content: v.NullableSchema<v.StringSchema<undefined>, undefined>;
1725
2708
  readonly source: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
1726
2709
  readonly version: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
@@ -2054,7 +3037,7 @@ export declare const MAX_SYNC_AUX_BATCH = 100;
2054
3037
  */
2055
3038
  export declare const MAX_RULE_MANIFEST_FILES = 500;
2056
3039
  /**
2057
- * 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.
2058
3041
  *
2059
3042
  * `path` is relative to that repo root, in exactly the form `payloadPath`
2060
3043
  * takes at import time (`packages/cli/src/rules/discover.ts`), so
@@ -2197,18 +3180,18 @@ export type SessionSelfReport = v.InferOutput<typeof SessionSelfReportSchema>;
2197
3180
  /**
2198
3181
  * The CLI entry point a sync came from, when that entry point is a hook.
2199
3182
  *
2200
- * **One member on purpose.** `mossbear session-start` is the command
3183
+ * **One member on purpose.** `mossbear refresh` is the command
2201
3184
  * `mossbear init` registers as the `SessionStart` hook, and nothing else runs
2202
3185
  * it — so a request carrying this value is proof that the hooks a project was
2203
3186
  * set up with are firing, which is the one onboarding fact the dashboard could
2204
3187
  * not previously observe. The other two hooks (`Stop`, `SessionEnd`) both run
2205
- * `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
2206
3189
  * requests are therefore indistinguishable from a manual sync and are
2207
3190
  * deliberately not named here rather than guessed at.
2208
3191
  *
2209
3192
  * Optional on the envelope, and its absence means only "not known to be a
2210
3193
  * session-start sync" — never "no hooks". A CLI predating this field sends
2211
- * none, and so does every ordinary `mossbear sync`.
3194
+ * none, and so does every ordinary `mossbear report`.
2212
3195
  *
2213
3196
  * A user can pass the flag that sets this by hand. That is not a privilege
2214
3197
  * boundary: the value is scoped to the caller's own account and the only thing
@@ -2400,12 +3383,12 @@ export declare const DashboardSyncRequestSchema: v.ObjectSchema<{
2400
3383
  readonly cliVersion: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.NonEmptyAction<string, undefined>, v.MaxLengthAction<string, 64, undefined>]>, undefined>;
2401
3384
  /**
2402
3385
  * Sessions whose agent context has ended, named by the CLI's `SessionEnd`
2403
- * hook (`mossbear sync --session-complete`) — never by its per-turn `Stop` hook.
3386
+ * hook (`mossbear complete`) — never by its per-turn `Stop` hook.
2404
3387
  * The server closes those sessions' runs; every other session in the payload
2405
3388
  * stays open.
2406
3389
  *
2407
3390
  * Session-keyed rather than a single envelope-level boolean, because one
2408
- * `mossbear sync` uploads every session with pending actions and chunks them
3391
+ * `mossbear report` uploads every session with pending actions and chunks them
2409
3392
  * across several requests. A boolean would close sessions that merely had a
2410
3393
  * backlog, and would close a session before the batches carrying the rest of
2411
3394
  * its actions had arrived. The CLI therefore names a session here only on the
@@ -2600,7 +3583,7 @@ export declare const ActionEntrySchema: v.ObjectSchema<{
2600
3583
  * This is what makes a skill load ride the action stream instead of the
2601
3584
  * transcript. `skill_usage` — the other place a loaded skill name is
2602
3585
  * recorded — is populated by `extractSessionUsage`, which returns empty unless
2603
- * `mossbear sync` is given `--transcripts-dir`, and the hook `mossbear init`
3586
+ * `mossbear report` is given `--transcripts-dir`, and the hook `mossbear init`
2604
3587
  * installs never passes one. So the transcript path has no data in a normal
2605
3588
  * session, while an action definitionally syncs.
2606
3589
  */
@@ -2616,7 +3599,7 @@ export declare const ActionEntrySchema: v.ObjectSchema<{
2616
3599
  * (`packages/cli/src/action-queue.ts`) builds the wire payload field by
2617
3600
  * field and does not include this one; transcripts are disclosed as
2618
3601
  * local-only in the dashboard's own privacy disclosure, and a path is still
2619
- * 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
2620
3603
  * the transcript for a session it is already uploading without searching for
2621
3604
  * it.
2622
3605
  *
@@ -3490,7 +4473,8 @@ export declare function parseContextItem(data: unknown): {
3490
4473
  id: string;
3491
4474
  type: string;
3492
4475
  name: string;
3493
- contentType: string;
4476
+ role: string | null;
4477
+ format: string | null;
3494
4478
  content: string | null;
3495
4479
  origin?: string | null | undefined;
3496
4480
  version?: number | undefined;
@@ -3514,13 +4498,20 @@ export declare function parseContextItem(data: unknown): {
3514
4498
  replyToId: string | null;
3515
4499
  }[] | undefined;
3516
4500
  updatedAt: string;
4501
+ gitSource?: {
4502
+ projectId: string;
4503
+ commitSha: string;
4504
+ branch?: string | undefined;
4505
+ } | null | undefined;
4506
+ removed?: true | undefined;
3517
4507
  };
3518
4508
  export declare function parseContextItemsResponse(data: unknown): {
3519
4509
  items: {
3520
4510
  id: string;
3521
4511
  type: string;
3522
4512
  name: string;
3523
- contentType: string;
4513
+ role: string | null;
4514
+ format: string | null;
3524
4515
  content: string | null;
3525
4516
  origin?: string | null | undefined;
3526
4517
  version?: number | undefined;
@@ -3544,6 +4535,12 @@ export declare function parseContextItemsResponse(data: unknown): {
3544
4535
  replyToId: string | null;
3545
4536
  }[] | undefined;
3546
4537
  updatedAt: string;
4538
+ gitSource?: {
4539
+ projectId: string;
4540
+ commitSha: string;
4541
+ branch?: string | undefined;
4542
+ } | null | undefined;
4543
+ removed?: true | undefined;
3547
4544
  }[];
3548
4545
  untrusted?: {
3549
4546
  token: string;
@@ -3554,20 +4551,26 @@ export declare function parseContextItemsResponse(data: unknown): {
3554
4551
  };
3555
4552
  export declare function parsePushContextRequest(data: unknown): {
3556
4553
  name: string;
3557
- contentType: "document" | "reference" | "asset";
4554
+ contentType: "content" | "asset";
3558
4555
  content: string;
3559
4556
  itemId?: string | undefined;
3560
4557
  origin?: string | null | undefined;
3561
4558
  sourceItemIds?: string[] | undefined;
3562
4559
  path?: string | null | undefined;
3563
4560
  projectId?: string | undefined;
4561
+ gitSource?: {
4562
+ projectId: string;
4563
+ commitSha: string;
4564
+ branch?: string | undefined;
4565
+ } | undefined;
3564
4566
  };
3565
4567
  export declare function parsePushContextResponse(data: unknown): {
3566
4568
  item: {
3567
4569
  id: string;
3568
4570
  type: string;
3569
4571
  name: string;
3570
- contentType: string;
4572
+ role: string | null;
4573
+ format: string | null;
3571
4574
  content: string | null;
3572
4575
  origin?: string | null | undefined;
3573
4576
  version?: number | undefined;
@@ -3591,6 +4594,12 @@ export declare function parsePushContextResponse(data: unknown): {
3591
4594
  replyToId: string | null;
3592
4595
  }[] | undefined;
3593
4596
  updatedAt: string;
4597
+ gitSource?: {
4598
+ projectId: string;
4599
+ commitSha: string;
4600
+ branch?: string | undefined;
4601
+ } | null | undefined;
4602
+ removed?: true | undefined;
3594
4603
  };
3595
4604
  created: boolean;
3596
4605
  };
@@ -3601,13 +4610,20 @@ export declare function parseUpdateContextItemRequest(data: unknown): {
3601
4610
  expectedVersion?: number | undefined;
3602
4611
  projectId?: string | undefined;
3603
4612
  sourceItemIds?: string[] | undefined;
4613
+ gitSource?: {
4614
+ projectId: string;
4615
+ commitSha: string;
4616
+ branch?: string | undefined;
4617
+ } | undefined;
4618
+ removed?: true | undefined;
3604
4619
  };
3605
4620
  export declare function parseUpdateContextItemResponse(data: unknown): {
3606
4621
  item: {
3607
4622
  id: string;
3608
4623
  type: string;
3609
4624
  name: string;
3610
- contentType: string;
4625
+ role: string | null;
4626
+ format: string | null;
3611
4627
  content: string | null;
3612
4628
  origin?: string | null | undefined;
3613
4629
  version?: number | undefined;
@@ -3631,6 +4647,12 @@ export declare function parseUpdateContextItemResponse(data: unknown): {
3631
4647
  replyToId: string | null;
3632
4648
  }[] | undefined;
3633
4649
  updatedAt: string;
4650
+ gitSource?: {
4651
+ projectId: string;
4652
+ commitSha: string;
4653
+ branch?: string | undefined;
4654
+ } | null | undefined;
4655
+ removed?: true | undefined;
3634
4656
  };
3635
4657
  updated: boolean;
3636
4658
  };
@@ -3639,6 +4661,12 @@ export declare function parseUpdateContextItemBody(data: unknown): {
3639
4661
  content?: string | undefined;
3640
4662
  expectedVersion?: number | undefined;
3641
4663
  projectId?: string | undefined;
4664
+ gitSource?: {
4665
+ projectId: string;
4666
+ commitSha: string;
4667
+ branch?: string | undefined;
4668
+ } | undefined;
4669
+ removed?: true | undefined;
3642
4670
  sourceItemIds?: string[] | undefined;
3643
4671
  };
3644
4672
  export declare function parseContextItemResponse(data: unknown): {
@@ -3646,7 +4674,8 @@ export declare function parseContextItemResponse(data: unknown): {
3646
4674
  id: string;
3647
4675
  type: string;
3648
4676
  name: string;
3649
- contentType: string;
4677
+ role: string | null;
4678
+ format: string | null;
3650
4679
  content: string | null;
3651
4680
  origin?: string | null | undefined;
3652
4681
  version?: number | undefined;
@@ -3670,6 +4699,12 @@ export declare function parseContextItemResponse(data: unknown): {
3670
4699
  replyToId: string | null;
3671
4700
  }[] | undefined;
3672
4701
  updatedAt: string;
4702
+ gitSource?: {
4703
+ projectId: string;
4704
+ commitSha: string;
4705
+ branch?: string | undefined;
4706
+ } | null | undefined;
4707
+ removed?: true | undefined;
3673
4708
  };
3674
4709
  };
3675
4710
  export declare function parseArchiveContextItemResponse(data: unknown): {
@@ -3678,7 +4713,8 @@ export declare function parseArchiveContextItemResponse(data: unknown): {
3678
4713
  id: string;
3679
4714
  type: string;
3680
4715
  name: string;
3681
- contentType: string;
4716
+ role: string | null;
4717
+ format: string | null;
3682
4718
  content: string | null;
3683
4719
  origin?: string | null | undefined;
3684
4720
  version?: number | undefined;
@@ -3702,12 +4738,18 @@ export declare function parseArchiveContextItemResponse(data: unknown): {
3702
4738
  replyToId: string | null;
3703
4739
  }[] | undefined;
3704
4740
  updatedAt: string;
4741
+ gitSource?: {
4742
+ projectId: string;
4743
+ commitSha: string;
4744
+ branch?: string | undefined;
4745
+ } | null | undefined;
4746
+ removed?: true | undefined;
3705
4747
  };
3706
4748
  };
3707
4749
  export declare function parseInboxCaptureRequest(data: unknown): {
3708
4750
  id?: string | undefined;
3709
4751
  bundleId?: string | null | undefined;
3710
- contentType: "document" | "reference" | "asset";
4752
+ contentType: "content" | "asset";
3711
4753
  content: string;
3712
4754
  name?: string | undefined;
3713
4755
  source?: string | undefined;
@@ -3717,7 +4759,8 @@ export declare function parseInboxCaptureResponse(data: unknown): {
3717
4759
  id: string;
3718
4760
  type: string;
3719
4761
  name: string;
3720
- contentType: string;
4762
+ role: string | null;
4763
+ format: string | null;
3721
4764
  content: string | null;
3722
4765
  source?: string | null | undefined;
3723
4766
  version?: number | undefined;
@@ -3730,7 +4773,8 @@ export declare function parseInboxListResponse(data: unknown): {
3730
4773
  id: string;
3731
4774
  type: string;
3732
4775
  name: string;
3733
- contentType: string;
4776
+ role: string | null;
4777
+ format: string | null;
3734
4778
  content: string | null;
3735
4779
  source?: string | null | undefined;
3736
4780
  version?: number | undefined;
@@ -4023,6 +5067,35 @@ export declare function parseGuideHistoryResponse(data: unknown): {
4023
5067
  note: string;
4024
5068
  };
4025
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
+ };
4026
5099
  export declare function parseRunGradeRequest(data: unknown): {
4027
5100
  session?: string | undefined;
4028
5101
  agent_session?: string | undefined;