@lucern/sdk 0.2.0-alpha.5 → 0.2.0-alpha.7

package/src/controlObjectOwnership.ts

@@ -0,0 +1,286 @@
+/** All recognized control object kinds in the ownership model. */
+export const CONTROL_OBJECT_KINDS = [
+  "tenant",
+  "workspace",
+  "principal",
+  "tool",
+  "pack",
+  "ontology",
+  "belief",
+  "policy_rule",
+] as const;
+/** A kind of control object (tenant, workspace, principal, tool, etc.). */
+export type ControlObjectKind = (typeof CONTROL_OBJECT_KINDS)[number];
+
+/** Canonical ownership scopes: platform, tenant, workspace, or resource. */
+export const CONTROL_OBJECT_OWNER_SCOPES = [
+  "platform",
+  "tenant",
+  "workspace",
+  "resource",
+] as const;
+/** The scope level that canonically owns a control object. */
+export type ControlObjectOwnerScope =
+  (typeof CONTROL_OBJECT_OWNER_SCOPES)[number];
+
+/** UI surfaces authorized to edit control objects. */
+export const CONTROL_OBJECT_EDIT_SURFACES = [
+  "platform_admin",
+  "tenant_admin",
+  "workspace_admin",
+  "graph_worktree",
+] as const;
+/** A UI surface authorized to mutate a control object (platform admin, tenant admin, etc.). */
+export type ControlObjectEditSurface =
+  (typeof CONTROL_OBJECT_EDIT_SURFACES)[number];
+
+/** Rules governing how control object configuration flows through the scope hierarchy. */
+export const CONTROL_OBJECT_INHERITANCE_RULES = [
+  "none",
+  "platform_seed_to_tenant",
+  "tenant_default_to_workspace",
+  "workspace_narrowing_only",
+  "pack_overlay_to_tenant",
+  "topic_lineage_to_resource",
+] as const;
+/** How a control object's configuration propagates through scope hierarchy. */
+export type ControlObjectInheritanceRule =
+  (typeof CONTROL_OBJECT_INHERITANCE_RULES)[number];
+
+/** Scope of impact when a control object is modified. */
+export const CONTROL_OBJECT_BLAST_RADII = [
+  "platform",
+  "tenant",
+  "workspace",
+  "resource",
+] as const;
+/** The furthest scope impacted by a mutation to a control object. */
+export type ControlObjectBlastRadius = (typeof CONTROL_OBJECT_BLAST_RADII)[number];
+
+/** A single row in the ownership matrix describing who owns, edits, and inherits a control object. */
+export type ControlObjectOwnershipCase = {
+  caseKey: string;
+  caseLabel: string;
+  kind: ControlObjectKind;
+  canonicalOwnerScope: ControlObjectOwnerScope;
+  editSurface: ControlObjectEditSurface;
+  inheritanceRule: ControlObjectInheritanceRule;
+  blastRadius: ControlObjectBlastRadius;
+};
+
+/** Full ownership matrix keyed by control object kind. */
+export type ControlObjectOwnershipMatrix = Record<
+  ControlObjectKind,
+  readonly ControlObjectOwnershipCase[]
+>;
+
+/** Versioned ownership contract bundling all enums, the matrix, and flattened rows. */
+export type ControlObjectOwnershipContract = {
+  version: "1.0.0";
+  kinds: readonly ControlObjectKind[];
+  ownerScopes: readonly ControlObjectOwnerScope[];
+  editSurfaces: readonly ControlObjectEditSurface[];
+  inheritanceRules: readonly ControlObjectInheritanceRule[];
+  blastRadii: readonly ControlObjectBlastRadius[];
+  matrix: ControlObjectOwnershipMatrix;
+  rows: readonly ControlObjectOwnershipCase[];
+};
+
+function defineCases<const T extends readonly ControlObjectOwnershipCase[]>(
+  cases: T
+): T {
+  return cases;
+}
+
+/** Static ownership matrix mapping each control object kind to its ownership cases. */
+export const CONTROL_OBJECT_OWNERSHIP_MATRIX = {
+  tenant: defineCases([
+    {
+      caseKey: "platform-record",
+      caseLabel: "Platform Record",
+      kind: "tenant",
+      canonicalOwnerScope: "platform",
+      editSurface: "platform_admin",
+      inheritanceRule: "none",
+      blastRadius: "tenant",
+    },
+  ]),
+  workspace: defineCases([
+    {
+      caseKey: "tenant-workspace",
+      caseLabel: "Tenant Workspace",
+      kind: "workspace",
+      canonicalOwnerScope: "tenant",
+      editSurface: "tenant_admin",
+      inheritanceRule: "tenant_default_to_workspace",
+      blastRadius: "workspace",
+    },
+  ]),
+  principal: defineCases([
+    {
+      caseKey: "tenant-principal",
+      caseLabel: "Tenant Principal",
+      kind: "principal",
+      canonicalOwnerScope: "tenant",
+      editSurface: "tenant_admin",
+      inheritanceRule: "workspace_narrowing_only",
+      blastRadius: "resource",
+    },
+  ]),
+  tool: defineCases([
+    {
+      caseKey: "platform-core",
+      caseLabel: "Platform Core",
+      kind: "tool",
+      canonicalOwnerScope: "platform",
+      editSurface: "platform_admin",
+      inheritanceRule: "platform_seed_to_tenant",
+      blastRadius: "platform",
+    },
+    {
+      caseKey: "tenant-custom",
+      caseLabel: "Tenant Custom",
+      kind: "tool",
+      canonicalOwnerScope: "tenant",
+      editSurface: "tenant_admin",
+      inheritanceRule: "tenant_default_to_workspace",
+      blastRadius: "tenant",
+    },
+  ]),
+  pack: defineCases([
+    {
+      caseKey: "platform-definition",
+      caseLabel: "Platform Definition",
+      kind: "pack",
+      canonicalOwnerScope: "platform",
+      editSurface: "platform_admin",
+      inheritanceRule: "platform_seed_to_tenant",
+      blastRadius: "platform",
+    },
+    {
+      caseKey: "tenant-installation",
+      caseLabel: "Tenant Installation",
+      kind: "pack",
+      canonicalOwnerScope: "tenant",
+      editSurface: "tenant_admin",
+      inheritanceRule: "platform_seed_to_tenant",
+      blastRadius: "tenant",
+    },
+  ]),
+  ontology: defineCases([
+    {
+      caseKey: "platform-base",
+      caseLabel: "Platform Base",
+      kind: "ontology",
+      canonicalOwnerScope: "platform",
+      editSurface: "platform_admin",
+      inheritanceRule: "platform_seed_to_tenant",
+      blastRadius: "platform",
+    },
+    {
+      caseKey: "pack-overlay",
+      caseLabel: "Pack Overlay",
+      kind: "ontology",
+      canonicalOwnerScope: "platform",
+      editSurface: "platform_admin",
+      inheritanceRule: "pack_overlay_to_tenant",
+      blastRadius: "platform",
+    },
+    {
+      caseKey: "tenant-extension",
+      caseLabel: "Tenant Extension",
+      kind: "ontology",
+      canonicalOwnerScope: "tenant",
+      editSurface: "tenant_admin",
+      inheritanceRule: "topic_lineage_to_resource",
+      blastRadius: "tenant",
+    },
+  ]),
+  belief: defineCases([
+    {
+      caseKey: "topic-resource",
+      caseLabel: "Topic Resource",
+      kind: "belief",
+      canonicalOwnerScope: "resource",
+      editSurface: "graph_worktree",
+      inheritanceRule: "topic_lineage_to_resource",
+      blastRadius: "resource",
+    },
+  ]),
+  policy_rule: defineCases([
+    {
+      caseKey: "platform-baseline",
+      caseLabel: "Platform Baseline",
+      kind: "policy_rule",
+      canonicalOwnerScope: "platform",
+      editSurface: "platform_admin",
+      inheritanceRule: "platform_seed_to_tenant",
+      blastRadius: "platform",
+    },
+    {
+      caseKey: "tenant-bundle",
+      caseLabel: "Tenant Bundle",
+      kind: "policy_rule",
+      canonicalOwnerScope: "tenant",
+      editSurface: "tenant_admin",
+      inheritanceRule: "tenant_default_to_workspace",
+      blastRadius: "tenant",
+    },
+    {
+      caseKey: "workspace-override",
+      caseLabel: "Workspace Override",
+      kind: "policy_rule",
+      canonicalOwnerScope: "workspace",
+      editSurface: "workspace_admin",
+      inheritanceRule: "none",
+      blastRadius: "workspace",
+    },
+  ]),
+} as const satisfies ControlObjectOwnershipMatrix;
+
+function flattenOwnershipMatrix(
+  matrix: ControlObjectOwnershipMatrix
+): ControlObjectOwnershipCase[] {
+  return CONTROL_OBJECT_KINDS.flatMap((kind) => [...matrix[kind]]);
+}
+
+/** Flattened array of all ownership cases across all control object kinds. */
+export const CONTROL_OBJECT_OWNERSHIP_ROWS = Object.freeze(
+  flattenOwnershipMatrix(CONTROL_OBJECT_OWNERSHIP_MATRIX)
+);
+
+/** The canonical ownership contract exposed by the SDK. */
+export const CONTROL_OBJECT_OWNERSHIP_CONTRACT = {
+  version: "1.0.0",
+  kinds: CONTROL_OBJECT_KINDS,
+  ownerScopes: CONTROL_OBJECT_OWNER_SCOPES,
+  editSurfaces: CONTROL_OBJECT_EDIT_SURFACES,
+  inheritanceRules: CONTROL_OBJECT_INHERITANCE_RULES,
+  blastRadii: CONTROL_OBJECT_BLAST_RADII,
+  matrix: CONTROL_OBJECT_OWNERSHIP_MATRIX,
+  rows: CONTROL_OBJECT_OWNERSHIP_ROWS,
+} as const satisfies ControlObjectOwnershipContract;
+
+/**
+ * List ownership cases for one control-object kind or the full matrix.
+ */
+export function listControlObjectOwnershipCases(
+  kind?: ControlObjectKind
+): readonly ControlObjectOwnershipCase[] {
+  if (!kind) {
+    return CONTROL_OBJECT_OWNERSHIP_ROWS;
+  }
+  return CONTROL_OBJECT_OWNERSHIP_MATRIX[kind];
+}
+
+/**
+ * Get a specific ownership case by kind and case key.
+ */
+export function getControlObjectOwnershipCase(
+  kind: ControlObjectKind,
+  caseKey: string
+): ControlObjectOwnershipCase | undefined {
+  return CONTROL_OBJECT_OWNERSHIP_MATRIX[kind].find(
+    (ownershipCase) => ownershipCase.caseKey === caseKey
+  );
+}