@company-semantics/contracts 39.5.0 → 39.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "39.5.0",
+  "version": "39.6.0",
   "private": false,
   "repository": {
     "type": "git",

package/src/action-items/schemas.ts

@@ -70,8 +70,15 @@ export const ActionItemSchema = z.object({
   /** The thing it is about, as the user names it, e.g. "Sales.md". */
   contextLabel: z.string(),
   /**
-   * Where to go to RESOLVE it. An action item whose href only *shows* the thing
-   * is a notification, not an action item — see `./kinds`.
+   * Where to go to RESOLVE it — a RELATIVE app path, e.g.
+   * `/@acme/md/{docId}?share=1&request={id}`.
+   *
+   * Relative because the consumer is an in-app link and an absolute URL would
+   * drop the SPA on click. The equivalent notification builds the absolute form
+   * itself, because that one is leaving the building.
+   *
+   * An href that only *shows* the thing makes this a notification rather than
+   * an action item — see `./kinds`.
    */
   href: z.string(),
   createdAt: z.string(),

package/src/org/README.md

@@ -40,6 +40,8 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `COMPANY_MD_COLLAB_MAX_DOC_TEXT_BYTES` — Cap on the MATERIALIZED document text, in UTF-8 bytes of the expanded result.
 - `COMPANY_MD_COLLAB_MAX_PRESENCE_POSITION_CHARS` — Cap on ONE presence position blob (`anchor` or `head`), in base64 chars.
 - `COMPANY_MD_COLLAB_MAX_UPDATE_B64_CHARS` — Cap on ONE encoded update, measured on the base64 payload as it is sent.
+- `COMPANY_MD_COLLAB_PRESENCE_HEARTBEAT_MS` — The cadence clients must re-POST presence at.
+- `COMPANY_MD_COLLAB_PRESENCE_TTL_MS` — How long the server keeps a presence entry alive with no fresh signal.
 - `COMPANY_MD_COLLAB_TEXT_KEY` — The Y.Doc root key holding the document body — a CONTRACT, not a detail.
 - `CanonicalFacts` _(type)_
 - `CanonicalFactsSchema` — The full normalized batch an external-source adapter emits in one pass: every person, org unit, position…

package/src/org/company-md-collab.ts

@@ -74,6 +74,30 @@ export const COMPANY_MD_COLLAB_MAX_DOC_TEXT_BYTES = 1_000_000 as const;
  */
 export const COMPANY_MD_COLLAB_MAX_PRESENCE_POSITION_CHARS = 512 as const;
 
+/**
+ * How long the server keeps a presence entry alive with no fresh signal.
+ *
+ * A protocol promise, not a knob: it is how long a crashed editor haunts the
+ * roster, and BOTH sides have to reason about it. The server expires on it and
+ * broadcasts a synthetic departure; a client's own expiry net has to sit beyond
+ * it, because a client clock that could fire first would race the authority and
+ * evict peers whose heartbeat merely landed late.
+ *
+ * Lives here rather than in either implementation because the app cannot import
+ * from the backend, and a hand-copy in each repo is a silent-drift bug waiting
+ * to happen. See ADR-BE-439 and ADR-APP-089.
+ */
+export const COMPANY_MD_COLLAB_PRESENCE_TTL_MS = 30_000 as const;
+
+/**
+ * The cadence clients must re-POST presence at.
+ *
+ * Half {@link COMPANY_MD_COLLAB_PRESENCE_TTL_MS}, so one lost heartbeat never
+ * expires a live editor. Published so the client contract and the server bound
+ * are one number in one place.
+ */
+export const COMPANY_MD_COLLAB_PRESENCE_HEARTBEAT_MS = 15_000 as const;
+
 // ---------------------------------------------------------------------------
 // Sequences
 // ---------------------------------------------------------------------------

package/src/org/index.ts

@@ -235,6 +235,8 @@ export {
   COMPANY_MD_COLLAB_MAX_UPDATE_B64_CHARS,
   COMPANY_MD_COLLAB_MAX_DOC_TEXT_BYTES,
   COMPANY_MD_COLLAB_MAX_PRESENCE_POSITION_CHARS,
+  COMPANY_MD_COLLAB_PRESENCE_TTL_MS,
+  COMPANY_MD_COLLAB_PRESENCE_HEARTBEAT_MS,
   CompanyMdCollabSyncLimitsSchema,
   CompanyMdCollabSyncResponseSchema,
   CompanyMdCollabUpdateAcceptedSchema,