@company-semantics/contracts 27.3.0 → 27.4.0

package/package.json

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

package/src/api/generated-spec-hash.ts

@@ -1,3 +1,3 @@
 // AUTO-GENERATED — do not edit. Run pnpm generate:spec-hash to regenerate.
-export const SPEC_HASH = '409ce57139cd' as const;
-export const SPEC_HASH_FULL = '409ce57139cd78a8ec633efb516bc92ba81dd2cdaab0a4afe240d20c67bb6b1e' as const;
+export const SPEC_HASH = '090fb75c09a2' as const;
+export const SPEC_HASH_FULL = '090fb75c09a20a352791bd84163827b0b23d84b41b5f82c216eae20fa5a3909d' as const;

package/src/api/generated.ts

@@ -4440,6 +4440,13 @@ export interface components {
                 memberCount: number;
                 description?: string;
                 orderKey?: string;
+                /** @enum {string} */
+                discoverabilityPolicy: "org" | "owners";
+                /** @enum {string} */
+                classification: "public" | "internal" | "confidential" | "highly_confidential";
+                /** @enum {string} */
+                accessState?: "full" | "redacted_admin" | "locked_requestable";
+                canRequestAccess?: boolean;
             }[];
             nextCursor: string | null;
             hasMore: boolean;
@@ -4453,7 +4460,14 @@ export interface components {
             content: string;
             contentRedacted?: boolean;
             /** @enum {string} */
+            accessState?: "full" | "redacted_admin" | "locked_requestable";
+            canRequestAccess?: boolean;
+            /** @enum {string} */
             visibility: "private" | "unit" | "org";
+            /** @enum {string} */
+            discoverabilityPolicy: "org" | "owners";
+            /** @enum {string} */
+            classification: "public" | "internal" | "confidential" | "highly_confidential";
             parentId: string | null;
             owningUnitId: string | null;
             owner: {
@@ -8467,13 +8481,6 @@ export interface operations {
                 };
                 content?: never;
             };
-            /** @description Requires org.view_company_md scope */
-            403: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content?: never;
-            };
         };
     };
     companyMdContextDocSuggestions: {
@@ -8503,13 +8510,6 @@ export interface operations {
                 };
                 content?: never;
             };
-            /** @description Requires org.view_company_md scope */
-            403: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content?: never;
-            };
         };
     };
     searchCompanyMd: {

package/src/content/schemas.ts

@@ -59,6 +59,25 @@ const CompanyMdTreeNodeSchema = z.object({
   description: z.string().optional(),
   /** Fractional-index key for ordered entity wrappers (unit/context). */
   orderKey: z.string().optional(),
+  // Governance + discovery projections of the node (ADR-BE-348 / ADR-CTRL-194).
+  // Present on the TS `CompanyMdNodeIdentity` since the projection split but only
+  // now promoted into the published response schema. `discoverabilityPolicy`
+  // governs who knows the node exists; `classification` is the governance label
+  // (drives no permission).
+  discoverabilityPolicy: z.enum(["org", "owners"]),
+  classification: z.enum([
+    "public",
+    "internal",
+    "confidential",
+    "highly_confidential",
+  ]),
+  // Combined Authorization + Discovery read-state for the requesting actor
+  // (ADR-BE-348). Set on non-reader stubs the tree now surfaces; absent on
+  // full-read nodes (treat as `full`).
+  accessState: z
+    .enum(["full", "redacted_admin", "locked_requestable"])
+    .optional(),
+  canRequestAccess: z.boolean().optional(),
 });
 
 // ---------------------------------------------------------------------------
@@ -83,7 +102,26 @@ export const CompanyMdDocResponseSchema = z.object({
    * its body (ADR-BE-245). Omitted/`false` on the normal full-content path.
    */
   contentRedacted: z.boolean().optional(),
+  // Combined Authorization + Discovery read-state for the requesting actor
+  // (ADR-BE-348): `full` (reader), `redacted_admin` (inspectable metadata stub),
+  // `locked_requestable` (listed locked stub). Optional for back-compat with
+  // legacy paths that set only `contentRedacted`.
+  accessState: z
+    .enum(["full", "redacted_admin", "locked_requestable"])
+    .optional(),
+  /** Whether the requesting actor may request access (ADR-BE-348 / ADR-BE-338). */
+  canRequestAccess: z.boolean().optional(),
   visibility: z.enum(["private", "unit", "org"]),
+  // Governance + discovery projections (ADR-BE-348 / ADR-CTRL-194). Present on
+  // the TS contract since the projection split; now promoted into the published
+  // response schema so consumers receive them typed.
+  discoverabilityPolicy: z.enum(["org", "owners"]),
+  classification: z.enum([
+    "public",
+    "internal",
+    "confidential",
+    "highly_confidential",
+  ]),
   parentId: z.string().nullable(),
   owningUnitId: z.string().nullable(),
   owner: CompanyMdPersonSchema.nullable(),

package/src/org/company-md.ts

@@ -39,9 +39,26 @@ export type CompanyMdDiscoverabilityPolicy = "org" | "owners";
 
 /**
  * Information classification for a Company.md node — *what the document is*, for
- * governance, NOT permissions (ADR-CTRL-194 / ADR-BE-338). Later drives export
- * watermarking, share-approval gates, retrieval rules, and audit verbosity
- * without changing who can read. Named now; enforcement behaviors deferred.
+ * governance, NOT permissions (ADR-CTRL-194 / ADR-BE-338 / ADR-BE-348). It is the
+ * input to the Governance projection and NEVER participates in authorization or
+ * discovery (ADR-BE-348 invariant 4).
+ *
+ * The value is now emitted on the published response schemas (tree + doc) so a
+ * consumer can read it. Enforcement behaviors remain deferred — each is named
+ * with the concrete trigger that promotes it from decorative to enforced:
+ *
+ * - **Export watermarking** — wire when a doc-export/download surface ships
+ *   (`confidential`+ stamps the exporter identity + timestamp).
+ * - **Share-approval friction** — wire when external/cross-org sharing exists
+ *   (`highly_confidential` requires a second approver before an ACL grant lands).
+ * - **Retrieval rules** — wire when agent browsing / RAG over knowledge nodes is
+ *   on (`confidential`+ excluded from un-attributed retrieval contexts).
+ * - **Audit verbosity** — wire when the audit sink supports per-class verbosity
+ *   (`highly_confidential` reads emit a full access record, not a sampled one).
+ *
+ * Until those surfaces exist there is nothing to gate, so classification is
+ * carried, not enforced — a deliberate "named now, enforced on trigger" deferral,
+ * not an omission.
  */
 export type CompanyMdClassification =
   | "public"
@@ -159,6 +176,26 @@ export interface CompanyMdTreeNode extends CompanyMdNodeIdentity {
    * unordered types.
    */
   readonly orderKey?: string;
+  /**
+   * Combined Authorization + Discovery read-state of this tree node for the
+   * requesting actor (ADR-BE-348). The tree now surfaces discoverable nodes a
+   * non-reader cannot read, as stubs:
+   * - `full`: actor holds a read grant — the normal, fully-navigable node.
+   * - `redacted_admin`: non-reader at Discovery `inspectable` (oversight/owner) —
+   *   a metadata stub.
+   * - `locked_requestable`: non-reader at Discovery `listed` — a locked stub.
+   * Discovery `hidden` nodes are omitted from the tree entirely (no leak).
+   * Omitted on legacy/full-content nodes that predate the stub surface; treat an
+   * absent value as `full`.
+   */
+  readonly accessState?: "full" | "redacted_admin" | "locked_requestable";
+  /**
+   * Whether the requesting actor may request access to this node — the same
+   * resolver the read affordance uses (ADR-BE-348). Set on non-reader stubs so
+   * the tree can render a "Request access" affordance; absent/`false` on nodes
+   * the actor already reads.
+   */
+  readonly canRequestAccess?: boolean;
 }
 
 export interface CompanyMdDocCore extends CompanyMdNodeIdentity {