@mossbear/protocol 0.1.0-alpha.87 → 0.1.0-alpha.89

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.js CHANGED
@@ -9,7 +9,9 @@
9
9
  */
10
10
  import * as v from 'valibot';
11
11
  import { DISPLAY_NAME_REFUSED_CHARACTERS } from './bundleSlug.js';
12
- import { CONTEXT_CONTENT_KINDS, CONTEXT_ITEM_TYPES, CONTEXT_ITEM_TYPE_FILTER_VALUES, contextItemTypeOf, INBOX_CONTENT_TYPES, PUSH_CONTENT_TYPES, } from './contextKinds.js';
12
+ import { isBundleSlug } from './bundleSlug.js';
13
+ import { CONTEXT_CONTENT_KINDS, CONTEXT_ITEM_TYPES, CONTEXT_ITEM_TYPE_FILTER_VALUES, contextItemTypeOf, INBOX_CONTENT_TYPES, } from './contextKinds.js';
14
+ import { MAX_CONTEXT_CONTENT_BYTES, MAX_RAW_GUIDE_CONTENT_BYTES } from './limits.js';
13
15
  // ---------------------------------------------------------------------------
14
16
  // Core enum schemas
15
17
  // ---------------------------------------------------------------------------
@@ -94,8 +96,7 @@ const Sha256HexSchema = v.pipe(v.string(), v.regex(/^[a-f0-9]{64}$/i));
94
96
  // `SafeRelativePosixPathSchema` and `GuideDiscoveryRootSchema`: the bundle now
95
97
  // carries the same `(root, path)` pair the import payload does, and a `const`
96
98
  // cannot be referenced above its own declaration.
97
- /** Max serialized size (UTF-8 bytes) of an imported guide file's raw content. */
98
- export const MAX_RAW_GUIDE_CONTENT_BYTES = 512 * 1024;
99
+ export { MAX_RAW_GUIDE_CONTENT_BYTES };
99
100
  /** Max member files a single skill-md payload may carry. */
100
101
  export const MAX_SKILL_MEMBER_FILES = 64;
101
102
  const BoundedRawContentSchema = v.pipe(v.string(), v.check((value) => new TextEncoder().encode(value).length <= MAX_RAW_GUIDE_CONTENT_BYTES, `rawContent must be at most ${MAX_RAW_GUIDE_CONTENT_BYTES} bytes`));
@@ -190,7 +191,7 @@ export const RawGuideFilePayloadSchema = v.pipe(v.object({
190
191
  // - it is embedded verbatim in the guide's `origin` (`file:{format}:{path}`)
191
192
  // and parsed back out to place the file on disk. The writer that does so
192
193
  // is now the docs phase's projection resolver
193
- // (`packages/cli/src/docs/guide-projection.ts`), which rejects anything
194
+ // (`packages/cli/src/artifacts/guide-projection.ts`), which rejects anything
194
195
  // absolute, traversing or uncontained — so an unsafe path stores a guide
195
196
  // that can never round-trip. (`mossbear guides export` was the original
196
197
  // writer and skipped such a path *silently*; it was deleted by
@@ -363,7 +364,7 @@ export const RulesImportRequestSchema = v.object({
363
364
  * Deliberately looser than `RepoIdSchema`: a generated id is
364
365
  * `proj_`+hex, but a *declared* one is whatever a human committed —
365
366
  * `readRepoProjectId` accepts any non-empty trimmed string
366
- * (`packages/cli/src/docs/repo-config.ts`), and rejecting those here would
367
+ * (`packages/cli/src/artifacts/repo-config.ts`), and rejecting those here would
367
368
  * break a shipped contract. Constrained only as far as it must be to serve as
368
369
  * a storage key: no whitespace, no path separators, no control characters,
369
370
  * bounded length.
@@ -640,7 +641,7 @@ export const BUNDLE_NAME_MAX_LENGTH = 200;
640
641
  // ---------------------------------------------------------------------------
641
642
  // url-safe slug, unique per user. Lowercase alphanumerics + hyphens, must start
642
643
  // with an alphanumeric so it reads cleanly in a URL/path.
643
- export const BundleSlugSchema = v.pipe(v.string(), v.minLength(1), v.maxLength(64), v.regex(/^[a-z0-9][a-z0-9-]*$/, 'slug must be lowercase alphanumeric with hyphens'));
644
+ export const BundleSlugSchema = v.pipe(v.string(), v.check(isBundleSlug, 'slug must be lowercase alphanumeric with hyphens, at most 64 characters'));
644
645
  export const BundleSchema = v.object({
645
646
  id: v.string(),
646
647
  slug: BundleSlugSchema,
@@ -725,7 +726,7 @@ export const ResolvedSubscriptionSchema = v.object({
725
726
  * trip at all. Echoing a value the caller just sent would make the server look
726
727
  * like the authority on a fact it does not hold. The caller pairs this with
727
728
  * its own committed `deliver` to build the per-scope target set
728
- * (`packages/cli/src/docs/delivery.ts` → `deliveryBundles`).
729
+ * (`packages/cli/src/artifacts/delivery.ts` → `deliveryBundles`).
729
730
  *
730
731
  * Optional rather than nullable so a CLI built before this field parses a new
731
732
  * server's response unchanged, and a new CLI reads an old server's response as
@@ -901,9 +902,15 @@ export const RevokeScopedTokenRequestSchema = v.object({
901
902
  // one id, so no membership kind travels the wire. An older client may still send
902
903
  // `itemType` on attach (or `?itemType=` on detach); this schema is not strict, so
903
904
  // the field is dropped on parse rather than refused.
904
- export const AttachBundleMemberRequestSchema = v.object({
905
- itemId: v.pipe(v.string(), v.minLength(1)),
906
- });
905
+ /**
906
+ * The member to attach, by its artifact id. `itemId` is the name a CLI from before
907
+ * release step 2 sends; both are read, and the parsed value is always `artifactId`.
908
+ * Drop `itemId` once no such CLI is left to send it.
909
+ */
910
+ export const AttachBundleMemberRequestSchema = v.pipe(v.object({
911
+ artifactId: v.optional(v.pipe(v.string(), v.minLength(1))),
912
+ itemId: v.optional(v.pipe(v.string(), v.minLength(1))),
913
+ }), v.check((request) => request.artifactId !== undefined || request.itemId !== undefined, 'A member needs an artifactId.'), v.transform((request) => ({ artifactId: (request.artifactId ?? request.itemId) })));
907
914
  export const AttachBundleMemberResponseSchema = v.object({
908
915
  // False when the item was already a member — attach is idempotent, and the
909
916
  // caller (multi-select menu applying a diff) treats both as success.
@@ -913,7 +920,7 @@ export const DetachBundleMemberResponseSchema = v.object({
913
920
  detached: v.boolean(),
914
921
  });
915
922
  // Rename changes the display name only. The slug is the bundle's identity —
916
- // repos subscribe by slug in `.mossbear/config.json` → `docs.bundles`, and
923
+ // repos subscribe by slug in `.mossbear/config.json` → `bundles`, and
917
924
  // `mossbear pull <slug>` addresses it — so a slug change would silently break
918
925
  // every subscribed repo (context-bundle-authoring-plan.md → D14).
919
926
  /**
@@ -963,25 +970,10 @@ export const ContextItemTypeSchema = v.picklist(CONTEXT_ITEM_TYPES);
963
970
  * the release that moved the CLI's own vocabulary onto `content`.
964
971
  */
965
972
  export const ContextItemTypeFilterSchema = v.picklist(CONTEXT_ITEM_TYPE_FILTER_VALUES);
966
- // The contentType a caller may *create* through the context layer. `guide` is
967
- // deliberately absent, and stays absent after slice 2b-B made guides pushable:
968
- // this schema is reached only by POST (create) and the MCP `create_artifact`
969
- // tool — the PUT body carries no contentType at all
970
- // (`UpdateContextItemRequestSchema` below). So admitting `guide` here could
971
- // only legalize a *create*, which the endpoint cannot honor: POST always calls
972
- // `insertBundleGuideFile`, which writes a standalone guide_files row with
973
- // `guideId: null` and never the `guides` registration a guide needs, so the
974
- // caller would get a 201 for something that is not a guide. Updating an
975
- // existing guide needs nothing from this picklist — it is addressed by
976
- // `itemId` alone (`guide-versioned-identity-plan.md` → Slice 2b-B, the third
977
- // Codex constraint, resolved as "restrict to itemId-bearing updates").
978
- // (the `pushable` column of `CONTEXT_CONTENT_KINDS`).
979
- export const PushContentTypeSchema = v.picklist(PUSH_CONTENT_TYPES);
980
973
  // Inbox capture is text or an image today (image upload lands in Phase 2b) —
981
974
  // the `capturable` column of `CONTEXT_CONTENT_KINDS`.
982
975
  export const InboxContentTypeSchema = v.picklist(INBOX_CONTENT_TYPES);
983
- /** Max serialized size (UTF-8 bytes) of a pushed or captured item's content. */
984
- export const MAX_CONTEXT_CONTENT_BYTES = 256 * 1024;
976
+ export { MAX_CONTEXT_CONTENT_BYTES };
985
977
  const ContextContentSchema = v.pipe(v.string(), v.check((value) => new TextEncoder().encode(value).length <= MAX_CONTEXT_CONTENT_BYTES, `content must be at most ${MAX_CONTEXT_CONTENT_BYTES} bytes`));
986
978
  const ArtifactNameSchema = v.pipe(v.string(), v.minLength(1), v.maxLength(200));
987
979
  // The wire ceiling for an in-place update — see UpdateContextItemRequestSchema
@@ -1262,7 +1254,7 @@ const ContextItemObjectSchema = v.object({
1262
1254
  root: v.optional(v.nullable(GuideDiscoveryRootSchema)),
1263
1255
  path: v.optional(v.nullable(SafeRelativePosixPathSchema)),
1264
1256
  // The portable identity of the project this item belongs to — the `project.id`
1265
- // a repo commits to `.mossbear/config.json` (`packages/cli/src/docs/repo-config.ts:302-315`).
1257
+ // a repo commits to `.mossbear/config.json` (`packages/cli/src/artifacts/repo-config.ts:302-315`).
1266
1258
  // A project-scoped item carrying one belongs to *that* repo and nowhere else,
1267
1259
  // which is what lets the docs phase stop materializing a guide from repo X
1268
1260
  // into repo Z (`project-scope-git-owned-plan.md` → Approach 1).
@@ -1393,6 +1385,14 @@ export const ContextItemsResponseSchema = v.object({
1393
1385
  */
1394
1386
  untrusted: v.optional(v.nullable(GuideHistoryUntrustedSchema)),
1395
1387
  });
1388
+ /**
1389
+ * The bundle pull under its artifact name: the same members and comments as
1390
+ * {@link ContextItemsResponseSchema}, under `artifacts`.
1391
+ */
1392
+ export const BundleArtifactsResponseSchema = v.object({
1393
+ artifacts: v.array(ContextItemSchema),
1394
+ untrusted: v.optional(v.nullable(GuideHistoryUntrustedSchema)),
1395
+ });
1396
1396
  /**
1397
1397
  * How many bundles one comments read may name.
1398
1398
  *
@@ -1519,7 +1519,6 @@ const AgentCommentTargetIdSchema = v.pipe(v.string(), v.minLength(1), v.maxLengt
1519
1519
  export const AgentCommentRequestSchema = v.object({
1520
1520
  target: v.variant('kind', [
1521
1521
  v.object({ kind: v.literal('artifact'), id: AgentCommentTargetIdSchema }),
1522
- v.object({ kind: v.literal('item'), id: AgentCommentTargetIdSchema }),
1523
1522
  v.object({ kind: v.literal('session'), id: AgentCommentTargetIdSchema }),
1524
1523
  v.object({ kind: v.literal('reply'), id: AgentCommentTargetIdSchema }),
1525
1524
  ]),
@@ -1550,8 +1549,7 @@ export const AgentCommentResponseSchema = v.object({
1550
1549
  id: v.string(),
1551
1550
  threadId: v.string(),
1552
1551
  subject: v.object({
1553
- // `artifact` is the new name for `item`; a client reads either.
1554
- kind: v.picklist(['artifact', 'item', 'session']),
1552
+ kind: v.picklist(['artifact', 'session']),
1555
1553
  id: v.string(),
1556
1554
  }),
1557
1555
  body: v.string(),
@@ -1712,251 +1710,6 @@ export const CommentEvidenceResponseSchema = v.object({
1712
1710
  sessionCommentsWithheld: v.optional(v.pipe(v.number(), v.integer()), 0),
1713
1711
  untrusted: GuideHistoryUntrustedSchema,
1714
1712
  });
1715
- /** Max number of context item ids a push may cite as its transform sources. */
1716
- export const MAX_TRANSFORM_SOURCE_IDS = 100;
1717
- /**
1718
- * The ids of the caller-owned context items a pushed document was produced
1719
- * from (inbox captures, bundle items — any item the caller owns). Shared
1720
- * between the REST contract and the MCP tool's client-side arg validation so
1721
- * the two can't drift.
1722
- */
1723
- export const SourceItemIdsSchema = v.pipe(v.array(v.pipe(v.string(), v.minLength(1))), v.minLength(1), v.maxLength(MAX_TRANSFORM_SOURCE_IDS));
1724
- // The update-side variant: same element and upper bound, but an empty array is
1725
- // legal and means "clear the stored provenance". See
1726
- // `UpdateContextItemRequestSchema.sourceItemIds` for why the create side keeps
1727
- // the non-empty bound.
1728
- export const UpdatableSourceItemIdsSchema = v.pipe(v.array(v.pipe(v.string(), v.minLength(1))), v.maxLength(MAX_TRANSFORM_SOURCE_IDS));
1729
- // Push a canonical item into a bundle. `itemId` present → update in place (the
1730
- // MCP push maps to PUT); absent → create (maps to POST). The dedicated update
1731
- // schema below is what the PUT route validates.
1732
- //
1733
- // `sourceItemIds` (optional, on create and update alike) cites the context
1734
- // items the pushed document was produced from. **The server accepts and ignores
1735
- // it**: provenance is recorded per saved revision as `sources`
1736
- // (`ArtifactSourceRefSchema`), and the head list is no longer written. The field
1737
- // stays so a client that still sends it parses. Existing stored values are left
1738
- // as they are.
1739
- //
1740
- // `path` (optional) is the document's **placement**: where it sits in the tree
1741
- // of the repo that declared it, so the docs phase materializes it there instead
1742
- // of dropping a second copy into the bundle directory. It is accepted on update
1743
- // too (`UpdateContextItemRequestSchema.path`), which is what makes it a place
1744
- // the user can rearrange rather than a record of where the file came from.
1745
- //
1746
- // Three things about it are load-bearing:
1747
- //
1748
- // - It is the **same schema** `ContextItemSchema.path` uses on the read side
1749
- // (`:645`). A second rule here would let the server accept a row it then
1750
- // could not serialize, and a strict read schema fails the *whole* response
1751
- // server-side — so one bad row would take
1752
- // every other item in the bundle with it.
1753
- // - **Absent is legal and is the ordinary case**, not a migration artifact: a
1754
- // document authored in the dashboard never had a repo path. Absent keeps
1755
- // today's bundle-directory default, which the CLI already implements
1756
- // (`packages/cli/src/docs/guide-projection.ts:356-358`).
1757
- // - There is deliberately **no `root`**. The docs phase supplies only the
1758
- // project root (`packages/cli/src/docs/sync-docs.ts:1613-1617`), so `global`
1759
- // could never materialize, and with it refused a root field could only ever
1760
- // carry the value an absent root already means.
1761
- //
1762
- // The route additionally refuses a path that is agent guidance — `AGENTS.md`,
1763
- // anything under `.agents/` and friends — which the schema cannot express and
1764
- // which is checked with `isAgentGuidancePath`. Without it an agent could push a
1765
- // document that becomes a repo's guidance file on the next sync. The update
1766
- // routes apply the same refusal, since a movable path is a second entrance.
1767
- export const PushContextRequestSchema = v.object({
1768
- name: ArtifactNameSchema,
1769
- contentType: PushContentTypeSchema,
1770
- content: ContextContentSchema,
1771
- itemId: v.optional(v.string()),
1772
- origin: v.optional(v.nullable(v.string())),
1773
- sourceItemIds: v.optional(SourceItemIdsSchema),
1774
- path: v.optional(v.nullable(SafeRelativePosixPathSchema)),
1775
- /**
1776
- * The committed `project.id` of the checkout this write comes from, when it
1777
- * has one (`subscription-delivery-target-plan.md` → slice 3).
1778
- *
1779
- * It answers two questions, both about the writer's checkout:
1780
- *
1781
- * - **Is this write coming from the repo that owns these items?** Only a
1782
- * bundle that claims a home asks. A request that declares nothing — every
1783
- * dashboard edit — is not the home repo and is refused by name. Declaring an
1784
- * id grants nothing on its own: an unclaimed bundle ignores it for this
1785
- * purpose, and the caller must already be a member of the bundle's workspace
1786
- * to reach this route at all.
1787
- * - **Which repo is `path` placed in?** Stored beside `path` as the item's
1788
- * home, so the one repo that declared the path can hold the document there
1789
- * literally while every other subscriber mirrors it. Ignored without a
1790
- * `path`: a home places nothing when there is no path to place.
1791
- *
1792
- * **The stored home is not echoed back as `ContextItemSchema.projectId`.**
1793
- * That field tells a reader an item belongs to one repo and is not to be
1794
- * materialized anywhere else; a document's home only says where it lands.
1795
- *
1796
- * Parsed as {@link DeclaredProjectIdSchema} — the CLI config reader's own
1797
- * rule, trimmed and non-empty, and no stricter — so the stored home
1798
- * round-trips against the value a checkout reads.
1799
- */
1800
- projectId: v.optional(DeclaredProjectIdSchema),
1801
- /**
1802
- * Where the committed bytes in `content` came from, when this write is a
1803
- * publication (`artifact-ownership-and-delivery-plan.md` → slice 3). Present
1804
- * means git owns the resulting artifact: the commit is the authority and
1805
- * Mossbear distributes the revision rather than keeping a second editable
1806
- * copy.
1807
- *
1808
- * **Sending it is a claim about provenance, not an authorization.** The
1809
- * server still answers who may write here from bundle membership and the
1810
- * bundle's declared home, exactly as it does for `projectId` above; what this
1811
- * adds is the revision the bytes were read from, so a subscriber can answer
1812
- * "what did I get".
1813
- *
1814
- * **`path` is required alongside it and the route enforces that**, because
1815
- * the database will: `guide_files_git_source_subset` admits only "repo id +
1816
- * path + sha all present" or the whole group absent, so a publication that
1817
- * named no path would fail at insert time with a constraint error instead of
1818
- * a sentence. Refused in the route rather than restated as a wire rule, for
1819
- * the reason `ContextItemSchema.gitSource` gives — a path this schema cannot
1820
- * parse is one item's problem, not the response's.
1821
- */
1822
- gitSource: v.optional(GitSourceSchema),
1823
- });
1824
- export const PushContextResponseSchema = v.object({
1825
- item: ContextItemSchema,
1826
- created: v.boolean(),
1827
- });
1828
- // Update a canonical item in place — the edit propagates to every bundle that
1829
- // references it. Both fields are optional so a partial update parses; the route
1830
- // rejects a body that changes nothing.
1831
- export const UpdateContextItemRequestSchema = v.object({
1832
- itemId: v.pipe(v.string(), v.minLength(1)),
1833
- name: v.optional(ArtifactNameSchema),
1834
- // Bounded by the **guide** cap, not the context cap, because an update can
1835
- // target either kind and the two disagree: an imported guide body may be up
1836
- // to `MAX_RAW_GUIDE_CONTENT_BYTES` (512 KiB) while a pushed/captured item
1837
- // caps at `MAX_CONTEXT_CONTENT_BYTES` (256 KiB). Before slice 2b-B that gap
1838
- // was unreachable — guides could not be pushed — and closing it by lowering
1839
- // the import cap would reject guides that already import today, while raising
1840
- // the context cap would double what the context layer accepts for everything.
1841
- // So this is only the wire ceiling (the DoS bound); the *kind-specific* limit
1842
- // is enforced in `updateBundleGuideFileContent`, which is the one place that
1843
- // has already resolved which kind of row it is about to write. Enforcing it
1844
- // in the route instead would be exactly the rule a future caller forgets
1845
- // (Planning Principle 14).
1846
- content: v.optional(UpdatableContentSchema),
1847
- // Optimistic-concurrency precondition: the version the caller last read (from
1848
- // `ContextItemSchema.version`). When present and it no longer matches the
1849
- // current version, the update is rejected with 409 instead of silently
1850
- // clobbering a concurrent write. Omit it to keep last-write-wins behavior.
1851
- expectedVersion: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1))),
1852
- /**
1853
- * The committed `project.id` of the checkout this write comes from — same
1854
- * meaning and same two uses as on `PushContextRequestSchema`: a bundle that
1855
- * claims a home accepts writes only from that repo, and a request declaring
1856
- * nothing is not it; and when this update sets `path`, it is stored as the
1857
- * repo that path is placed in. Parsed as on `PushContextRequestSchema`.
1858
- */
1859
- projectId: v.optional(DeclaredProjectIdSchema),
1860
- /**
1861
- * Move the document: its new placement, or `null` to take the placement away
1862
- * so it lands in the bundle folder again.
1863
- *
1864
- * **Three states, the same shape `sourceItemIds` takes.** Omitted leaves the
1865
- * stored path and its home alone — every name or body edit. A path replaces
1866
- * both: the path, and the home as `projectId` above declares it, since a path
1867
- * is relative to the repo that declared it. `null` clears both.
1868
- *
1869
- * The same schema as the create side and the read side, for the reason
1870
- * `PushContextRequestSchema` gives, and the same refusals in the routes —
1871
- * agent guidance, Mossbear's state directory, git's.
1872
- *
1873
- * **Documents only.** A guide's path is its discovery path, which import
1874
- * reconciles on; moving it here would fork it from the file it came from, so
1875
- * the routes refuse it on a guide by name. A git-published artifact cannot
1876
- * drop its path either, because the published-source group is only legal
1877
- * beside one.
1878
- */
1879
- path: v.optional(v.nullable(SafeRelativePosixPathSchema)),
1880
- // Replaces the item's stored provenance. An update re-derives the document,
1881
- // so the citation records where the item's *current* body came from; leaving
1882
- // the previous ids in place would describe content that no longer exists.
1883
- // This used to be rejected outright, because a transform was graded once at
1884
- // creation — that reason was deleted with the grader
1885
- // (`transform-grading-removal-plan.md`).
1886
- //
1887
- // Three states, which is why this is not `SourceItemIdsSchema`: **omitted**
1888
- // leaves the stored ids alone (a name-only or provenance-preserving edit),
1889
- // a **non-empty** list replaces them, and **`[]` clears them**. Without the
1890
- // empty case an item rewritten from scratch could never shed provenance that
1891
- // no longer describes it — the silently-wrong record this field's own
1892
- // rationale argues against. `POST` keeps the non-empty bound: there is
1893
- // nothing to clear on a create, so `[]` there would only be a second way to
1894
- // say "no sources" alongside omitting the field.
1895
- sourceItemIds: v.optional(UpdatableSourceItemIdsSchema),
1896
- /**
1897
- * The revision this update's bytes were read from — same meaning as on
1898
- * `PushContextRequestSchema` above, and the field that makes a republication
1899
- * advance an artifact's provenance rather than leave it pointing at the
1900
- * commit it was first published from.
1901
- *
1902
- * **Omitted leaves the stored group alone; it never clears it.** An update
1903
- * that says nothing about provenance is a name or body edit, not a claim that
1904
- * the artifact stopped being git-owned — and an absent key that silently
1905
- * un-owned a row would hand a subscriber write access by omission, which is
1906
- * the failure the whole ownership model exists to prevent. Ownership is given
1907
- * up by promotion, not by a missing field.
1908
- */
1909
- gitSource: v.optional(GitSourceSchema),
1910
- /**
1911
- * Tombstone this artifact: the commit that published it has since deleted the
1912
- * file, so the revision stops being delivered while the row and its version
1913
- * history stay where they are.
1914
- *
1915
- * **A verb, not a column state**, the same shape the dashboard's own removal
1916
- * takes (`~/zero/mutators.ts` → `guideFiles.update`'s `removed`). There is no
1917
- * writable field here that a removal and an ordinary edit could disagree
1918
- * about, and `literal(true)` is what keeps `removed: false` from reading as a
1919
- * request to bring something back — un-removing is republishing, which is an
1920
- * ordinary content write.
1921
- *
1922
- * **`gitSource` is required alongside it and the route enforces that.** A
1923
- * tombstone's whole claim is *which revision removed the file*: without one
1924
- * the row would say an artifact stopped being delivered and be unable to say
1925
- * why, which is the silent withdrawal this field exists to replace. That also
1926
- * keeps the only writer of a removal here the publication path — this is not
1927
- * a general delete verb for the context layer.
1928
- *
1929
- * **Never sent with `content`.** A removal has no bytes; a body carrying both
1930
- * is two answers to one question and the route refuses it rather than picking.
1931
- */
1932
- removed: v.optional(v.literal(true)),
1933
- });
1934
- export const UpdateContextItemResponseSchema = v.object({
1935
- item: ContextItemSchema,
1936
- updated: v.boolean(),
1937
- });
1938
- // The same edit addressed by URL instead of by body field. The item-scoped
1939
- // `PUT /api/v1/context/items/:itemId` takes the id from the path, so carrying it
1940
- // in the body as well would let the two disagree and force the route to pick a
1941
- // winner. Derived with `v.omit` rather than re-declared, so the updatable fields
1942
- // and their bounds cannot drift between the two shapes.
1943
- export const UpdateContextItemBodySchema = v.omit(UpdateContextItemRequestSchema, [
1944
- 'itemId',
1945
- ]);
1946
- /** A single canonical item, for the item-scoped read route. */
1947
- export const ContextItemResponseSchema = v.object({
1948
- item: ContextItemSchema,
1949
- });
1950
- // `POST /api/v1/context/items/:itemId/archive`. A boolean, not a count: the
1951
- // route addresses exactly one item and answers 404 when it does not resolve, so
1952
- // there is no "succeeded on 0 of 1" state left for a number to express. That
1953
- // ambiguity is the bug this route exists to remove — the batch inbox endpoint
1954
- // answered `200 {archived: 0}` for an item it declined to touch
1955
- // (`inbox-as-view-plan.md` → Evidence).
1956
- export const ArchiveContextItemResponseSchema = v.object({
1957
- archived: v.boolean(),
1958
- item: ContextItemSchema,
1959
- });
1960
1713
  // A capture id the *client* minted, so a note has a name before it has a
1961
1714
  // server — `offline-doc-editing-plan.md` → slice 4.
1962
1715
  //
@@ -2075,18 +1828,13 @@ export const ArtifactVersionDetailSchema = v.object({
2075
1828
  createdAt: v.string(),
2076
1829
  });
2077
1830
  /** The item routes' names for the version schemas, kept while those routes are served. */
2078
- export const ContextItemVersionSchema = ArtifactVersionSchema;
2079
- export const ContextItemVersionDetailSchema = ArtifactVersionDetailSchema;
2080
1831
  // Newest-first page of a doc's version summaries. `nextCursor` is the version
2081
1832
  // number to pass back as `?before=` for the following (older) page, or null
2082
1833
  // once the oldest version has been returned.
2083
- export const ContextItemVersionsResponseSchema = v.object({
2084
- versions: v.array(ContextItemVersionSchema),
1834
+ export const BundleArtifactVersionsResponseSchema = v.object({
1835
+ versions: v.array(ArtifactVersionSchema),
2085
1836
  nextCursor: v.nullable(v.number()),
2086
1837
  });
2087
- export const ContextItemVersionResponseSchema = v.object({
2088
- version: ContextItemVersionDetailSchema,
2089
- });
2090
1838
  /** Default and max page size for the version-history list endpoint. */
2091
1839
  export const DEFAULT_VERSIONS_LIMIT = 50;
2092
1840
  export const MAX_VERSIONS_LIMIT = 200;
@@ -2295,6 +2043,15 @@ export const RemoveArtifactRequestSchema = v.strictObject({
2295
2043
  */
2296
2044
  projectId: DeclaredProjectIdSchema,
2297
2045
  expectedVersion: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1))),
2046
+ /**
2047
+ * The one bundle this removal is for — a withdrawal, where a declaration
2048
+ * stopped covering the path for that bundle while the file is still there.
2049
+ * A tombstone stops delivery everywhere, so the server refuses with a 409
2050
+ * tagged `shared-artifact` when the artifact belongs to any other bundle,
2051
+ * checked under the same lock an attach takes. Absent for a committed
2052
+ * deletion, which removes the artifact from every bundle.
2053
+ */
2054
+ onlyMemberOf: v.optional(v.pipe(v.string(), v.minLength(1), v.maxLength(128))),
2298
2055
  });
2299
2056
  /** Archive an artifact. The body is optional; `projectId` is the same checkout claim as on update. */
2300
2057
  export const ArchiveArtifactRequestSchema = v.strictObject({
@@ -2997,21 +2754,19 @@ export const ExtractedFeedbackBatchSchema = v.object({
2997
2754
  // ---------------------------------------------------------------------------
2998
2755
  // Agent config schema
2999
2756
  // ---------------------------------------------------------------------------
3000
- // AgentConfig is the input shape `packages/projections`' renderers take.
2757
+ // AgentConfig was the input shape of `packages/projections`' renderers, which
2758
+ // were deleted with `projections-compat-renderers-dead`.
3001
2759
  // EvalRequest/EvalResult/Finding and ProjectionRequest/ProjectionResult used
3002
2760
  // to wrap it for the CLI's on-device grader and a projection wire envelope;
3003
2761
  // both are gone, and had zero consumers outside this package's own tests.
3004
2762
  //
3005
2763
  // The CLI command that produced these — `mossbear guides project` — is gone
3006
- // too (`guides-project-removal`). The schema stays because the renderers it
3007
- // fed still type against it (`packages/projections/src/agents-dir.ts:14`,
3008
- // `claude-md.ts:21`, `claude-rules.ts:21`, `cursor-rules.ts:21`); those
3009
- // renderers now have no non-test caller, and retiring them is its own row.
2764
+ // too (`guides-project-removal`). The schema stays only because it is a
2765
+ // published export: nothing in the repo reads it since the renderers were
2766
+ // removed, and dropping it is a semver judgment, not a cleanup.
3010
2767
  //
3011
- // `parseAgentConfig` below lost its only non-test caller to that same deletion.
3012
- // It is dead code today, kept for now because this package is published and
3013
- // dropping a public wrapper is a semver judgment; it is filed with the eight
3014
- // other unused `parse*` wrappers rather than deleted here.
2768
+ // `parseAgentConfig` below has no non-test caller for the same reason; it stays
2769
+ // until someone decides to drop a published wrapper.
3015
2770
  export const AgentConfigSchema = v.object({
3016
2771
  id: v.string(),
3017
2772
  name: v.string(),
@@ -3553,8 +3308,7 @@ export const ArtifactFeedbackResponseSchema = v.object({
3553
3308
  // Run grade — one run's verdict, for the terminal (`GET /api/v1/runs/grade`)
3554
3309
  // ---------------------------------------------------------------------------
3555
3310
  /**
3556
- * One run's grade, read by `mossbear sessions` and by the one line
3557
- * `mossbear sessions last` prints when the previous session violated a guide.
3311
+ * One session's grade, read by the MCP `session_digest` tool.
3558
3312
  *
3559
3313
  * The loop this closes: a session ends with "synced N item(s) to the
3560
3314
  * dashboard." and the verdict exists only in the dashboard. This is the read
@@ -3579,8 +3333,8 @@ export const SessionGradeRequestSchema = v.pipe(v.object({
3579
3333
  agent_session: v.optional(SessionGradeIdentifierSchema),
3580
3334
  /**
3581
3335
  * Opt in to the session digest: the grade plus the turns, self-report and
3582
- * git position of the session. Omitted, the small grade payload that
3583
- * `mossbear sessions` and session start read is unchanged.
3336
+ * git position of the session. Omitted, the small grade payload is
3337
+ * returned unchanged.
3584
3338
  */
3585
3339
  detail: v.optional(v.literal('digest')),
3586
3340
  }), v.check((request) => (request.session !== undefined) !== (request.agent_session !== undefined), 'Pass exactly one of session or agent_session'));
@@ -3616,11 +3370,8 @@ export const SessionGradeStateSchema = v.picklist([
3616
3370
  * session never engaged. It is not `unguided`, which is an action-level word,
3617
3371
  * and neither is ever restated in terms of the other.
3618
3372
  */
3619
- export const SessionGuideVerdictValueSchema = v.picklist([
3620
- 'aligned',
3621
- 'misaligned',
3622
- 'not_applicable',
3623
- ]);
3373
+ export const SESSION_GUIDE_VERDICTS = ['aligned', 'misaligned', 'not_applicable'];
3374
+ export const SessionGuideVerdictValueSchema = v.picklist(SESSION_GUIDE_VERDICTS);
3624
3375
  /** One guide's verdict for the run, with the grader's reasoning wrapped. */
3625
3376
  export const SessionGradeGuideSchema = v.object({
3626
3377
  guideId: NonEmptyStringSchema,
@@ -3800,27 +3551,16 @@ export const SearchFrontmatterSchema = v.pipe(v.record(v.pipe(v.string(), v.rege
3800
3551
  export const SEARCH_COMMENT_AUTHOR_KINDS = ['person', 'agent', 'mossbear'];
3801
3552
  export const SearchCommentAuthorKindSchema = v.picklist(SEARCH_COMMENT_AUTHOR_KINDS);
3802
3553
  /**
3803
- * What a comment is attached to. `item` is a guide or a document; `session` is a
3804
- * run the caller made. Session comments are the caller's own and never reach a
3805
- * workspace-mate.
3554
+ * What a comment is attached to. `artifact` is a guide or a document; `session`
3555
+ * is a run the caller made. Session comments are the caller's own and never reach
3556
+ * a workspace-mate.
3806
3557
  */
3807
- export const SEARCH_COMMENT_SUBJECT_KINDS = ['item', 'session'];
3808
- export const SearchCommentSubjectKindSchema = v.picklist(SEARCH_COMMENT_SUBJECT_KINDS);
3809
3558
  /**
3810
3559
  * The subject kinds a client names in a search: `artifact`, never its older
3811
3560
  * name `item`.
3812
3561
  */
3813
3562
  export const SEARCH_COMMENT_SUBJECT_KIND_NAMES = ['artifact', 'session'];
3814
- /**
3815
- * The subject kinds a search request may name. `artifact` is the new name for
3816
- * `item` and means the same subjects; both are accepted until every client sends
3817
- * `artifact`, while hits and the advertised list above still say `item`.
3818
- */
3819
- export const SEARCH_COMMENT_SUBJECT_KIND_FILTERS = [
3820
- ...SEARCH_COMMENT_SUBJECT_KINDS,
3821
- 'artifact',
3822
- ];
3823
- export const SearchCommentSubjectKindFilterSchema = v.picklist(SEARCH_COMMENT_SUBJECT_KIND_FILTERS);
3563
+ export const SearchCommentSubjectKindFilterSchema = v.picklist(SEARCH_COMMENT_SUBJECT_KIND_NAMES);
3824
3564
  /**
3825
3565
  * What a user turn was, as the session classifier labels it. The same
3826
3566
  * vocabulary the classifier writes; a `turns` search may keep only some.
@@ -4021,9 +3761,9 @@ const searchCommentHitFields = {
4021
3761
  * A comment on a guide or document that matched. `body` and `itemName` and
4022
3762
  * `workspaceName` are wrapped in `untrusted`'s markers.
4023
3763
  */
4024
- export const SearchItemCommentHitSchema = v.object({
3764
+ export const SearchArtifactCommentHitSchema = v.object({
4025
3765
  ...searchCommentHitFields,
4026
- subjectKind: v.literal('item'),
3766
+ subjectKind: v.literal('artifact'),
4027
3767
  itemId: NonEmptyStringSchema,
4028
3768
  /**
4029
3769
  * The guide the item belongs to, or null for a standalone document. A comment
@@ -4060,17 +3800,8 @@ export const SearchSessionCommentHitSchema = v.object({
4060
3800
  sessionId: NonEmptyStringSchema,
4061
3801
  matchedIn: v.literal('body'),
4062
3802
  });
4063
- /**
4064
- * The same hit under the new name for its subject (one-artifact Stage 3): a
4065
- * client reads either until every server sends `artifact`.
4066
- */
4067
- export const SearchArtifactCommentHitSchema = v.object({
4068
- ...SearchItemCommentHitSchema.entries,
4069
- subjectKind: v.literal('artifact'),
4070
- });
4071
3803
  export const SearchCommentHitSchema = v.variant('subjectKind', [
4072
3804
  SearchArtifactCommentHitSchema,
4073
- SearchItemCommentHitSchema,
4074
3805
  SearchSessionCommentHitSchema,
4075
3806
  ]);
4076
3807
  /**
@@ -4279,32 +4010,11 @@ export function parseUpdateBundleResponse(data) {
4279
4010
  export function parseDeleteBundleResponse(data) {
4280
4011
  return v.parse(DeleteBundleResponseSchema, data);
4281
4012
  }
4282
- export function parseContextItem(data) {
4283
- return v.parse(ContextItemSchema, data);
4284
- }
4285
4013
  export function parseContextItemsResponse(data) {
4286
4014
  return v.parse(ContextItemsResponseSchema, data);
4287
4015
  }
4288
- export function parsePushContextRequest(data) {
4289
- return v.parse(PushContextRequestSchema, data);
4290
- }
4291
- export function parsePushContextResponse(data) {
4292
- return v.parse(PushContextResponseSchema, data);
4293
- }
4294
- export function parseUpdateContextItemRequest(data) {
4295
- return v.parse(UpdateContextItemRequestSchema, data);
4296
- }
4297
- export function parseUpdateContextItemResponse(data) {
4298
- return v.parse(UpdateContextItemResponseSchema, data);
4299
- }
4300
- export function parseUpdateContextItemBody(data) {
4301
- return v.parse(UpdateContextItemBodySchema, data);
4302
- }
4303
- export function parseContextItemResponse(data) {
4304
- return v.parse(ContextItemResponseSchema, data);
4305
- }
4306
- export function parseArchiveContextItemResponse(data) {
4307
- return v.parse(ArchiveContextItemResponseSchema, data);
4016
+ export function parseBundleArtifactsResponse(data) {
4017
+ return v.parse(BundleArtifactsResponseSchema, data);
4308
4018
  }
4309
4019
  export function parseInboxCaptureRequest(data) {
4310
4020
  return v.parse(InboxCaptureRequestSchema, data);
@@ -4315,11 +4025,8 @@ export function parseInboxCaptureResponse(data) {
4315
4025
  export function parseInboxListResponse(data) {
4316
4026
  return v.parse(InboxListResponseSchema, data);
4317
4027
  }
4318
- export function parseContextItemVersionsResponse(data) {
4319
- return v.parse(ContextItemVersionsResponseSchema, data);
4320
- }
4321
- export function parseContextItemVersionResponse(data) {
4322
- return v.parse(ContextItemVersionResponseSchema, data);
4028
+ export function parseBundleArtifactVersionsResponse(data) {
4029
+ return v.parse(BundleArtifactVersionsResponseSchema, data);
4323
4030
  }
4324
4031
  export function parseInboxArchiveRequest(data) {
4325
4032
  return v.parse(InboxArchiveRequestSchema, data);