borgmcp-shared 0.10.1 → 0.11.0

package/CONTRIBUTING.md

@@ -19,9 +19,9 @@ Use Node.js 20 or newer, then run:
 
 ```sh
 npm install
-npm test
-npm run check
 npm run build
+npm run check
+npm test
 npm pack --dry-run
 ```
 

package/README.md

@@ -1,8 +1,8 @@
 # borgmcp-shared
 
 `borgmcp-shared` is the implementation-neutral contract package for Borg MCP.
-It contains protocol types, domain helpers, built-in cube templates, and
-portable conformance vectors used by Borg MCP clients and server implementations.
+It contains protocol types, domain helpers, built-in cube templates, and portable
+conformance vectors that Borg MCP client and server implementations can run.
 Its pure ESM helpers and generated TypeScript declarations run consistently
 across host environments with zero runtime dependencies.
 
@@ -12,7 +12,7 @@ across host environments with zero runtime dependencies.
 npm install borgmcp-shared
 ```
 
-The package is ESM-only and supports Node.js 20 or newer.
+The package is ESM-only and supports Node.js 22.12.0 or newer.
 
 ## Public API
 
@@ -53,9 +53,9 @@ The supported subpaths are:
 - `borgmcp-shared/drone-address`: stable short drone-address rendering.
 - `borgmcp-shared/runtime-metadata`: pure validation and canonical repository
   identity helpers for advisory local seat metadata.
+- `borgmcp-shared/package.json`: package metadata.
 
-Generated declaration files are included in every published package. Public
-functions and contracts include API documentation in their TypeScript sources.
+Generated declaration files are included in the published package.
 
 ## Handshake
 
@@ -99,11 +99,12 @@ authority: there is no capability negotiation, and client and server ship and
 update together as one clean-slate product. The attach request envelope still
 decodes its version before any payload as defense in depth.
 
-Every JSON coordination request and successful JSON response is carried inside
-`ProtocolEnvelope<T>`. Failures use `ProtocolErrorEnvelope`. The only bodyless
-exceptions are the `204` liveness and acknowledgement responses. Payload codecs
-are exported separately so adapters can validate the envelope first and then
-validate the operation-specific payload without accepting ambiguous fields.
+Versioned JSON coordination requests and successful responses are carried inside
+`ProtocolEnvelope<T>`. Failures use `ProtocolErrorEnvelope`. The credential-free
+protocol preflight uses its exact tag-only shape; `204` liveness and
+acknowledgement responses are bodyless. Payload codecs are exported separately
+so adapters can validate the envelope first and then validate the
+operation-specific payload without accepting ambiguous fields.
 Cube managers reassign a seat with `PATCH /api/cubes/:cubeId/drones/:droneId`
 and evict one with `DELETE` on the same path. Both operations use strict
 versioned request and success envelopes. An evicted seat's former bearer receives
@@ -121,8 +122,8 @@ ordinary ungranted enrollment, cube creation, pending enrollment, and retry cont
 ## Conformance
 
 Server and client implementations should run the vectors exported from
-`borgmcp-shared/conformance` against their adapters. The vectors and runner are
-readonly data rather than Vitest-specific helpers, so they work with any test
+`borgmcp-shared/conformance` against their adapters. The vectors are readonly
+data, and the runner is test-runner-independent code, so they work with any test
 runner supported by the implementation. Cases cover HTTP and canonical errors,
 credential misuse, isolation and revocation, SSE framing/replay/cursor ordering,
 executable enrollment authority/retry/mismatch/redaction and cube-create
@@ -144,9 +145,9 @@ historical values so existing registry entries remain compatible.
 Implement `ConformanceEnvironment` with raw responses from the target adapter,
 then call `runAdapterConformance`. The runner creates and decodes envelopes,
 drives state transitions, and decides pass/fail; adapters do not submit expected
-results. Each server or client adapter runs this single portable suite against
-its local/self-hosted implementation. The package does not define a second
-authority, migration target, or fallback implementation.
+results. A server or client adapter can run the portable suite against its
+local/self-hosted implementation. The package does not define a second authority,
+migration target, or fallback implementation.
 
 The package's own suite covers built-in templates, role-section patching,
 broadcast high-water-mark ordering, drone-address formatting, runtime metadata

package/dist/protocol/contract.d.ts

@@ -2,7 +2,7 @@ import { ErrorCode } from './errors.js';
 import { type ProtocolVersion } from './version.js';
 import type { DroneRuntimeMetadata, DroneRuntimeMetadataPatch } from './types.js';
 export declare const SHARED_PACKAGE_NAME: "borgmcp-shared";
-export declare const SHARED_PACKAGE_VERSION: "0.10.1";
+export declare const SHARED_PACKAGE_VERSION: "0.11.0";
 export declare const DECISION_TEXT_MAX_BYTES: 512;
 export declare const ROLE_TEXT_MAX_BYTES: 51200;
 export declare const HEALTH_PATH: "/healthz";

package/dist/protocol/contract.js

@@ -2,7 +2,7 @@ import { ErrorCode } from './errors.js';
 import { PROTOCOL_VERSION } from './version.js';
 import { canonicalizeRepositoryIdentity, RuntimeMetadataValidationError, validateRuntimeMetadata, validateRuntimeMetadataPatch, validateRuntimeMetadataReportState, } from '../runtime-metadata.js';
 export const SHARED_PACKAGE_NAME = 'borgmcp-shared';
-export const SHARED_PACKAGE_VERSION = '0.10.1';
+export const SHARED_PACKAGE_VERSION = '0.11.0';
 export const DECISION_TEXT_MAX_BYTES = 512;
 export const ROLE_TEXT_MAX_BYTES = 51_200;
 export const HEALTH_PATH = '/healthz';

package/dist/templates.d.ts

@@ -51,7 +51,7 @@ export declare const WAKE_PATH_MONITOR_DISCIPLINE = "\n\nWake discipline:\n- Use
 export declare const WORKER_BUNDLE_DRY_RUN_DISCIPLINE = "\n\nEnvironment-owned verification:\n- When a required check needs permissions or an environment this seat lacks, report the exact check and revision.\n- The coordinating seat routes that one check to an authorized operator; it does not broaden the implementation slice.\n- A result from another revision does not satisfy the gate.";
 export declare const PUSH_DISCIPLINE_COORDINATOR = "\n\nPush discipline:\n- Before pushing an integration result, fetch, verify the target and exact revision, and confirm the worktree is clean.\n- Do not force-push or move an existing tag without explicit recovery authority.";
 export declare const PUSH_DISCIPLINE_BUILDER = "\n\nPush discipline:\n- Push only the assigned branch after verifying the staged paths and final diff.\n- Do not force-push, rebase a shared branch, or publish from a local substitute artifact.";
-export declare const SAME_REPOSITORY_WORKFLOW_DISCIPLINE = "\n\nSame-repository worktrees and handover:\n- One seat uses one stable worktree, created once at assimilation under the standard worktree root and approved once by the operator. All seats for a repository are worktrees of the same clone family, sharing its object database and refs.\n- Start each new work item by switching branches in that seat's worktree with `git checkout -b <branch>`; never create a new worktree or folder per work item.\n- Create a branch only for a routed work item and announce its name in STARTING. One branch equals one work item and one owning seat; hand a branch to another seat only through an explicit log event.\n- Use merge-only history: no rebases and no force-pushes, because another seat may have the branch checked out or fetched.\n- Hand over a ref and exact commit SHA, never a filesystem path. Reviewers check out the SHA in their own worktree with `git checkout --detach <SHA>`; never read another seat's folder. Each review round binds to one exact SHA, and a new SHA restarts the gate sequence.\n- With a hosted origin, push the branch at creation with `git push -u origin <branch>`; a branch is cube-visible and REVIEW-READY only after that push.\n- With no hosted remote, the commit itself is the durable handover artifact because clone-family worktrees share refs; omit the push step. If push/fetch semantics are needed locally, use a local bare repository as the origin path.\n- Put all scratch work \u2014 detached review checkouts, clean-environment verification rigs, fake HOMEs, unpacked artifacts, and throwaway worktrees \u2014 under `~/.borg/scratch/<your-seat-label>/`; never use `/tmp` or an ad-hoc path. Scratch contents are disposable and must be cleaned up with the work.\n- After every merge to the protected or main branch, broadcast the merge SHA. When an origin exists, include `git fetch origin && git merge origin/main` as the merge-only sync instruction.";
+export declare const SAME_REPOSITORY_WORKFLOW_DISCIPLINE = "\n\nSame-repository workflow policy:\n- Start a routed work item on its own branch with `git checkout -b <branch>`. Announce its name in STARTING. One branch equals one work item and one owning seat.\n- Use merge-only history: no rebases and no force-pushes.\n- Hand over the exact commit SHA. Each review round binds to one exact SHA, and a new SHA restarts the gate sequence.\n- Run `git remote get-url origin` to determine whether a hosted origin exists.\n- When that command succeeds, publish the branch with `git push -u origin <branch>`; the branch is REVIEW-READY only after that push and exact remote-head verification.\n- When that command fails because no origin exists, omit the push; the work is REVIEW-READY when its exact commit SHA is available through the project review mechanism.\n- After every merge to the protected or main branch, broadcast the merge SHA.";
 export declare const UNIVERSAL_SAFETY_DISCIPLINES: string[];
 export declare const ROLE_SCOPED_SAFETY_DISCIPLINES: string[];
 export declare const DRONE_ADDRESSING_CONVENTION = "\n\nDrone addressing:\n- Route directed work with the stable short UUID shown by Borg, not a mutable display label.\n- Keep each dispatch self-contained: recipient, exact item, first action, and completion evidence.";

package/dist/templates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../src/templates.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,iBAAiB,EAAE,MAAM,CAAC;IAC1B,oBAAoB,EAAE,MAAM,CAAC;IAC7B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,OAAO,EAAE,WAAW,GAAG,UAAU,CAAC;IAClC,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,SAAS,CAAC,EAAE,UAAU,GAAG,YAAY,CAAC;CACvC;AAED,MAAM,MAAM,eAAe,GAAG,oBAAoB,EAAE,CAAC;AAErD,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,iBAAiB,EAAE,MAAM,CAAC;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gBAAgB,CAAC,EAAE,eAAe,CAAC;CACpC;AAED,eAAO,MAAM,6BAA6B,qBAAqB,CAAC;AAEhE,eAAO,MAAM,+BAA+B;;;;;;;;;;;;EAgBlC,CAAC;AAEX,eAAO,MAAM,qBAAqB,gdAOuD,CAAC;AAI1F,eAAO,MAAM,gCAAgC,+YAMoC,CAAC;AAElF,eAAO,MAAM,mCAAmC,qgBAQ8D,CAAC;AAE/G,eAAO,MAAM,uCAAuC,iVAGmQ,CAAC;AAExT,eAAO,MAAM,2BAA2B,4RAGwN,CAAC;AAEjQ,eAAO,MAAM,oBAAoB,mcAMgF,CAAC;AAElH,eAAO,MAAM,kCAAkC,mSAK8E,CAAC;AAE9H,eAAO,MAAM,sCAAsC,kTAKmC,CAAC;AAEvF,eAAO,MAAM,4BAA4B,+cAMiE,CAAC;AAE3G,eAAO,MAAM,gCAAgC,gVAKe,CAAC;AAE7D,eAAO,MAAM,2BAA2B,oOAIyC,CAAC;AAElF,eAAO,MAAM,uBAAuB,sMAIsD,CAAC;AAE3F,eAAO,MAAM,mCAAmC,s4DAW+I,CAAC;AAEhM,eAAO,MAAM,4BAA4B,UAAiC,CAAC;AAE3E,eAAO,MAAM,8BAA8B,UAQ1C,CAAC;AAEF,eAAO,MAAM,2BAA2B,4NAI2D,CAAC;AAyhBpG,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAI9C,CAAC;AAEF,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAEzD;AAED,wBAAgB,iBAAiB,IAAI,MAAM,EAAE,CAE5C;AAED,wBAAgB,6BAA6B,CAC3C,gBAAgB,EAAE,MAAM,EACxB,QAAQ,EAAE,QAAQ,GAAG,IAAI,GACxB,MAAM,CAGR;AAED,wBAAgB,4BAA4B,CAC1C,oBAAoB,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC/C,QAAQ,EAAE,QAAQ,GACjB,MAAM,GAAG,IAAI,CAGf;AAED,wBAAgB,+BAA+B,CAC7C,gBAAgB,EAAE,eAAe,GAAG,IAAI,GAAG,SAAS,EACpD,QAAQ,EAAE,QAAQ,GAAG,IAAI,GACxB,eAAe,GAAG,IAAI,CAExB"}
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../src/templates.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,iBAAiB,EAAE,MAAM,CAAC;IAC1B,oBAAoB,EAAE,MAAM,CAAC;IAC7B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,OAAO,EAAE,WAAW,GAAG,UAAU,CAAC;IAClC,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,SAAS,CAAC,EAAE,UAAU,GAAG,YAAY,CAAC;CACvC;AAED,MAAM,MAAM,eAAe,GAAG,oBAAoB,EAAE,CAAC;AAErD,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,iBAAiB,EAAE,MAAM,CAAC;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gBAAgB,CAAC,EAAE,eAAe,CAAC;CACpC;AAED,eAAO,MAAM,6BAA6B,qBAAqB,CAAC;AAEhE,eAAO,MAAM,+BAA+B;;;;;;;;;;;;EAgBlC,CAAC;AAEX,eAAO,MAAM,qBAAqB,gdAOuD,CAAC;AAI1F,eAAO,MAAM,gCAAgC,+YAMoC,CAAC;AAElF,eAAO,MAAM,mCAAmC,qgBAQ8D,CAAC;AAE/G,eAAO,MAAM,uCAAuC,iVAGmQ,CAAC;AAExT,eAAO,MAAM,2BAA2B,4RAGwN,CAAC;AAEjQ,eAAO,MAAM,oBAAoB,mcAMgF,CAAC;AAElH,eAAO,MAAM,kCAAkC,mSAK8E,CAAC;AAE9H,eAAO,MAAM,sCAAsC,kTAKmC,CAAC;AAEvF,eAAO,MAAM,4BAA4B,+cAMiE,CAAC;AAE3G,eAAO,MAAM,gCAAgC,gVAKe,CAAC;AAE7D,eAAO,MAAM,2BAA2B,oOAIyC,CAAC;AAElF,eAAO,MAAM,uBAAuB,sMAIsD,CAAC;AAE3F,eAAO,MAAM,mCAAmC,i3BAS8B,CAAC;AAE/E,eAAO,MAAM,4BAA4B,UAAiC,CAAC;AAE3E,eAAO,MAAM,8BAA8B,UAQ1C,CAAC;AAEF,eAAO,MAAM,2BAA2B,4NAI2D,CAAC;AA+pBpG,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAI9C,CAAC;AAEF,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAEzD;AAED,wBAAgB,iBAAiB,IAAI,MAAM,EAAE,CAE5C;AAED,wBAAgB,6BAA6B,CAC3C,gBAAgB,EAAE,MAAM,EACxB,QAAQ,EAAE,QAAQ,GAAG,IAAI,GACxB,MAAM,CAGR;AAED,wBAAgB,4BAA4B,CAC1C,oBAAoB,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC/C,QAAQ,EAAE,QAAQ,GACjB,MAAM,GAAG,IAAI,CAGf;AAED,wBAAgB,+BAA+B,CAC7C,gBAAgB,EAAE,eAAe,GAAG,IAAI,GAAG,SAAS,EACpD,QAAQ,EAAE,QAAQ,GAAG,IAAI,GACxB,eAAe,GAAG,IAAI,CAExB"}