@company-semantics/contracts 1.11.1 → 1.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "1.11.1",
+  "version": "1.12.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -104,7 +104,8 @@
     "generate:api": "pnpm generate:api-types && pnpm generate:spec-hash",
     "generate:api-types": "openapi-typescript openapi/backend.yaml -o src/api/generated.ts",
     "generate:openapi-routes": "tsx scripts/generate-openapi-routes.ts",
-    "generate:api-types:check": "openapi-typescript openapi/backend.yaml -o /tmp/cs-api-types-check.ts && diff -q src/api/generated.ts /tmp/cs-api-types-check.ts"
+    "generate:api-types:check": "openapi-typescript openapi/backend.yaml -o /tmp/cs-api-types-check.ts && diff -q src/api/generated.ts /tmp/cs-api-types-check.ts",
+    "generate:current": "tsx ../company-semantics-ci/scripts/generate-current.ts"
   },
   "packageManager": "pnpm@10.25.0",
   "engines": {

package/src/index.ts

@@ -288,6 +288,7 @@ export type {
   // Company.md domain types (PRD-00173)
   CompanyMdVisibility,
   CompanyMdDocLevel,
+  CompanyMdDocKind,
   CompanyMdNodeType,
   CompanyMdSource,
   CompanyMdDependency,

package/src/org/company-md.ts

@@ -6,15 +6,61 @@
  * @see PRD-00173 for design rationale
  */
 
-export type CompanyMdVisibility = 'public' | 'private';
+export type CompanyMdVisibility = "public" | "private";
 
-export type CompanyMdDocLevel = 'root' | 'department' | 'team' | 'context';
+/**
+ * @deprecated Since 1.12.0. `CompanyMdDocLevel` is superseded by `CompanyMdDocKind` + `depth`.
+ *
+ * The categorical naming here conflates structural position with a specific
+ * org's label vocabulary. `CompanyMdDocKind` ('root' | 'unit' | 'context')
+ * carries the structural discriminator; `depth` carries the position. Labels
+ * come from `org_level_config`.
+ *
+ * This alias remains valid through the next minor. It will be removed in the
+ * next major. Backend still emits these values on the wire until PRD-00524
+ * lands, after which `kind` + `depth` are canonical.
+ */
+export type CompanyMdDocLevel = "root" | "department" | "team" | "context";
 
-export type CompanyMdNodeType = 'company' | 'department' | 'team' | 'cross_team' | 'doc' | 'goal' | 'source' | 'map' | 'context_bank';
+/**
+ * Structural discriminator for a Company.md document.
+ *
+ * - `'root'`: the single org-wide doc (one per org).
+ * - `'unit'`: a doc owning an `org_unit` at depth 2..5. The specific depth is
+ *   carried separately on `depth`. Use `depth` + `org_level_config` for
+ *   presentation, never the string `'unit'` for user-visible labels.
+ * - `'context'`: a context-bank doc attached to a parent doc.
+ *
+ * Replaces the categorical `CompanyMdDocLevel` ('department' | 'team' ...).
+ */
+export type CompanyMdDocKind = "root" | "unit" | "context";
+
+/**
+ * Semantic node type used by the Company.md tree.
+ *
+ * Structural members ('company', 'department', 'team', 'cross_team') are
+ * @deprecated — use `'unit'` plus `depth` instead. They remain in the union
+ * through the next minor for backward compatibility and will be removed in
+ * the next major.
+ *
+ * Non-structural members ('doc', 'goal', 'source', 'map', 'context_bank')
+ * are not affected by the deprecation.
+ */
+export type CompanyMdNodeType =
+  | "company" // @deprecated — use 'unit' with depth=1
+  | "department" // @deprecated — use 'unit' with depth=2
+  | "team" // @deprecated — use 'unit' with depth=3
+  | "cross_team" // @deprecated — use 'unit' with a custom typeTag
+  | "unit"
+  | "doc"
+  | "goal"
+  | "source"
+  | "map"
+  | "context_bank";
 
 export interface CompanyMdSource {
   readonly label: string;
-  readonly sourceType: 'meeting' | 'document' | 'conversation' | 'manual';
+  readonly sourceType: "meeting" | "document" | "conversation" | "manual";
   readonly referencedAt: string;
 }
 
@@ -28,6 +74,15 @@ export interface CompanyMdNodeIdentity {
   readonly slug: string;
   readonly title: string;
   readonly level: CompanyMdDocLevel;
+  /**
+   * Authoritative structural position in the org tree (matches `nlevel(path)`
+   * on the owning org_unit). Null for non-structural nodes (context bank items,
+   * docs/goals/sources/maps that are not owned by a unit).
+   *
+   * Prefer this over `level` for structural reasoning. `level` is retained for
+   * backward compatibility and is @deprecated.
+   */
+  readonly depth: 1 | 2 | 3 | 4 | 5 | null;
   readonly parentId: string | null;
   readonly visibility: CompanyMdVisibility;
   /** Owning org_unit. Null for root docs or when the owning unit has been archived. */
@@ -53,9 +108,15 @@ export interface CompanyMdDocCore extends CompanyMdNodeIdentity {
 
 export interface CompanyMdDocCollaborators {
   readonly owner: { readonly id: string; readonly name: string } | null;
-  readonly coOwners: ReadonlyArray<{ readonly id: string; readonly name: string }>;
+  readonly coOwners: ReadonlyArray<{
+    readonly id: string;
+    readonly name: string;
+  }>;
   readonly canEdit: boolean;
-  readonly members: ReadonlyArray<{ readonly id: string; readonly name: string }>;
+  readonly members: ReadonlyArray<{
+    readonly id: string;
+    readonly name: string;
+  }>;
 }
 
 export interface CompanyMdDocRelations {
@@ -66,7 +127,9 @@ export interface CompanyMdDocRelations {
   readonly updatedAt: string;
 }
 
-export type CompanyMdDoc = CompanyMdDocCore & CompanyMdDocCollaborators & CompanyMdDocRelations;
+export type CompanyMdDoc = CompanyMdDocCore &
+  CompanyMdDocCollaborators &
+  CompanyMdDocRelations;
 
 /**
  * A context bank item — a company.md doc associated with one or more parent nodes.

package/src/org/index.ts

@@ -88,6 +88,7 @@ export { orderTreeNodes } from './tree-ordering';
 export type {
   CompanyMdVisibility,
   CompanyMdDocLevel,
+  CompanyMdDocKind,
   CompanyMdNodeType,
   CompanyMdSource,
   CompanyMdDependency,