@milaboratories/pl-model-common 1.28.0 → 1.30.0

package/dist/services/service_types.js

@@ -0,0 +1,28 @@
+import { ServiceAlreadyRegisteredError, ServiceInvalidIdError } from "../errors.js";
+
+//#region src/services/service_types.ts
+const SERVICE_ID_PATTERN = /^[a-zA-Z][a-zA-Z0-9]*$/;
+const { service, isNodeService } = (() => {
+	const typeMap = /* @__PURE__ */ new Map();
+	return {
+		service() {
+			return (options) => {
+				const { name, type } = options;
+				if (!SERVICE_ID_PATTERN.test(name)) throw new ServiceInvalidIdError(`Invalid service ID "${name}": must match ${SERVICE_ID_PATTERN}`);
+				if (typeMap.has(name)) throw new ServiceAlreadyRegisteredError(`Service "${name}" already registered`);
+				typeMap.set(name, type);
+				return name;
+			};
+		},
+		isNodeService(id) {
+			return typeMap.get(id) === "node";
+		}
+	};
+})();
+function serviceFnKey(serviceId, method = "") {
+	return `service:${serviceId}:${method}`;
+}
+
+//#endregion
+export { isNodeService, service, serviceFnKey };
+//# sourceMappingURL=service_types.js.map

package/dist/services/service_types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service_types.js","names":[],"sources":["../../src/services/service_types.ts"],"sourcesContent":["import type { Branded } from \"../branding\";\nimport { ServiceAlreadyRegisteredError, ServiceInvalidIdError } from \"../errors\";\nimport type { Services } from \"./service_declarations\";\n\nexport type ServiceTypesLike<\n  Model = unknown,\n  Ui = unknown,\n  Kind extends ServiceType = ServiceType,\n> = {\n  readonly __types?: { model: Model; ui: Ui; kind: Kind };\n};\n\nexport type InferServiceModel<S extends ServiceTypesLike> =\n  S extends ServiceTypesLike<infer M, unknown, ServiceType> ? M : unknown;\n\nexport type InferServiceUi<S extends ServiceTypesLike> =\n  S extends ServiceTypesLike<unknown, infer U, ServiceType> ? U : unknown;\n\nexport type InferServiceKind<S extends ServiceTypesLike> =\n  S extends ServiceTypesLike<unknown, unknown, infer K> ? K : ServiceType;\n\nexport type ServiceName<S extends ServiceTypesLike = ServiceTypesLike> = Branded<string, S>;\n\nexport type ServiceType = \"node\" | \"wasm\";\n\nconst SERVICE_ID_PATTERN = /^[a-zA-Z][a-zA-Z0-9]*$/;\n\nexport const { service, isNodeService } = (() => {\n  const typeMap = new Map<string, ServiceType>();\n  return {\n    service<Model, Ui>() {\n      return <K extends ServiceType, N extends string>(options: {\n        readonly type: K;\n        readonly name: N;\n      }): Branded<N, ServiceTypesLike<Model, Ui, K>> => {\n        const { name, type } = options;\n        if (!SERVICE_ID_PATTERN.test(name)) {\n          throw new ServiceInvalidIdError(\n            `Invalid service ID \"${name}\": must match ${SERVICE_ID_PATTERN}`,\n          );\n        }\n        if (typeMap.has(name)) {\n          throw new ServiceAlreadyRegisteredError(`Service \"${name}\" already registered`);\n        }\n        typeMap.set(name, type);\n        return name as Branded<N, ServiceTypesLike<Model, Ui, K>>;\n      };\n    },\n    isNodeService(id: ServiceName): boolean {\n      return typeMap.get(id) === \"node\";\n    },\n  };\n})();\n\nexport function serviceFnKey(serviceId: string, method = \"\"): string {\n  return `service:${serviceId}:${method}`;\n}\n\nexport type ServiceBrand<T> =\n  T extends Branded<string, infer S extends ServiceTypesLike> ? S : never;\n\nexport type ModelServiceFactoryMap<SMap extends Record<string, ServiceName>> = {\n  [K in keyof SMap]: (() => InferServiceModel<ServiceBrand<SMap[K]>>) | null;\n};\n\nexport type UiServiceFactoryMap<SMap extends Record<string, ServiceName>> = {\n  [K in keyof SMap]: (() => InferServiceUi<ServiceBrand<SMap[K]>>) | null;\n};\n\n/** Contract between any service provider and any service consumer. */\nexport interface ServiceDispatch {\n  getServiceNames(): ServiceName[];\n  getServiceMethods(serviceId: ServiceName): string[];\n  callServiceMethod(serviceId: ServiceName, method: string, ...args: unknown[]): unknown;\n}\n\n// Auto-derived types from the Services const in service_declarations.ts.\n// Adding a service to Services automatically updates all of these.\n\ntype SMap = typeof Services;\n\ntype ExtractServiceName<T> = T extends Branded<infer N extends string, any> ? N : never;\n\n/** Model-side service interfaces keyed by service name literal. */\nexport type ModelServices = {\n  [K in keyof SMap as ExtractServiceName<SMap[K]>]: InferServiceModel<ServiceBrand<SMap[K]>>;\n};\n\n/** UI-side service interfaces keyed by service name literal. */\nexport type UiServices = {\n  [K in keyof SMap as ExtractServiceName<SMap[K]>]: InferServiceUi<ServiceBrand<SMap[K]>>;\n};\n\n/** Map from Services keys to their unbranded string name literals. */\nexport type ServiceNameLiterals = {\n  [K in keyof SMap]: ExtractServiceName<SMap[K]>;\n};\n\n/** Auto-derived requires* feature flags from Services keys. */\nexport type ServiceRequireFlags = {\n  [K in keyof SMap as `requires${K & string}`]?: boolean;\n};\n\ntype UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (\n  k: infer I,\n) => void\n  ? I\n  : never;\n\nexport type RequireServices<T extends ServiceName> = UnionToIntersection<\n  T extends Branded<infer N extends string, infer S extends ServiceTypesLike>\n    ? Record<N, InferServiceModel<S>>\n    : never\n>;\n"],"mappings":";;;AAyBA,MAAM,qBAAqB;AAE3B,MAAa,EAAE,SAAS,yBAAyB;CAC/C,MAAM,0BAAU,IAAI,KAA0B;AAC9C,QAAO;EACL,UAAqB;AACnB,WAAiD,YAGC;IAChD,MAAM,EAAE,MAAM,SAAS;AACvB,QAAI,CAAC,mBAAmB,KAAK,KAAK,CAChC,OAAM,IAAI,sBACR,uBAAuB,KAAK,gBAAgB,qBAC7C;AAEH,QAAI,QAAQ,IAAI,KAAK,CACnB,OAAM,IAAI,8BAA8B,YAAY,KAAK,sBAAsB;AAEjF,YAAQ,IAAI,MAAM,KAAK;AACvB,WAAO;;;EAGX,cAAc,IAA0B;AACtC,UAAO,QAAQ,IAAI,GAAG,KAAK;;EAE9B;IACC;AAEJ,SAAgB,aAAa,WAAmB,SAAS,IAAY;AACnE,QAAO,WAAW,UAAU,GAAG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@milaboratories/pl-model-common",
-  "version": "1.28.0",
+  "version": "1.30.0",
   "description": "Platforma SDK Model",
   "files": [
     "./dist/**/*",
@@ -19,16 +19,16 @@
   "dependencies": {
     "canonicalize": "~2.1.0",
     "zod": "~3.23.8",
-    "@milaboratories/pl-error-like": "1.12.9",
-    "@milaboratories/helpers": "1.14.0"
+    "@milaboratories/helpers": "1.14.0",
+    "@milaboratories/pl-error-like": "1.12.9"
   },
   "devDependencies": {
     "@vitest/coverage-istanbul": "^4.0.18",
     "typescript": "~5.9.3",
     "vitest": "^4.0.18",
+    "@milaboratories/ts-configs": "1.2.2",
     "@milaboratories/ts-builder": "1.3.0",
-    "@milaboratories/build-configs": "1.5.2",
-    "@milaboratories/ts-configs": "1.2.2"
+    "@milaboratories/build-configs": "1.5.2"
   },
   "scripts": {
     "build": "ts-builder build --target node",

package/src/drivers/index.ts

@@ -7,5 +7,4 @@ export * from "./log";
 export * from "./ls";
 
 export * from "./pframe";
-export * from "./pspec";
 export * from "./ChunkedStreamReader";

package/src/drivers/pframe/driver.ts

@@ -1,6 +1,9 @@
 import type { Branded } from "../../branding";
 import type { PTable } from "./table";
-import type { PFrame } from "./pframe";
+import type { PFrame, PFrameDef } from "./pframe";
+import type { PColumn } from "./spec/spec";
+import type { PColumnValues, DataInfo } from "./data_info";
+import type { PTableDef, PTableDefV2 } from "./table_calculate";
 import type { AddParameterToAllMethods } from "./type_util";
 import type { PTableShape, PTableVector, TableRange } from "./data_types";
 import type { FindColumnsRequest, FindColumnsResponse } from "./find_columns";
@@ -16,6 +19,13 @@ export type PFrameHandle = Branded<string, "PFrame">;
 /** PFrame handle */
 export type PTableHandle = Branded<string, "PTable">;
 
+/** Model-side PFrame service — creates frames/tables from column definitions. */
+export interface PFrameModelDriver<Col = PColumn<string | PColumnValues | DataInfo<string>>> {
+  createPFrame(def: PFrameDef<Col>): PFrameHandle;
+  createPTable(def: PTableDef<Col>): PTableHandle;
+  createPTableV2(def: PTableDefV2<Col>): PTableHandle;
+}
+
 /** Allows to access main data layer features of platforma */
 export interface PFrameDriver {
   //

package/src/drivers/pframe/index.ts

@@ -15,3 +15,4 @@ export * from "./spec";
 export * from "./driver";
 
 export * from "./linker_columns";
+export * from "./spec_driver";

package/src/drivers/pframe/spec/spec.ts

@@ -303,7 +303,7 @@ export function isLinkerColumn(column: PColumnSpec): boolean {
  */
 export type AxisSpec = {
   /** Type of the axis value. Should not use non-key types like float or double. */
-  readonly type: ValueType;
+  readonly type: AxisValueType;
 
   /** Name of the axis */
   readonly name: string;
@@ -508,8 +508,6 @@ export function getNormalizedAxesList(axes: AxisSpec[]): AxisSpecNormalized[] {
       modifiedAxis.parentAxesSpec = parents.some((p) => p === undefined)
         ? []
         : (parents as AxisSpecNormalized[]);
-
-      delete modifiedAxis.annotations?.[Annotation.Parents];
     }
   });
 
@@ -543,6 +541,22 @@ export function getDenormalizedAxesList(axesSpec: AxisSpecNormalized[]): AxisSpe
   });
 }
 
+/**
+ * Resolve annotation-based parents (`pl7.app/parents`) to numeric `parentAxes`
+ * on a column spec. Returns the spec unchanged if all axes already use numeric
+ * indices or have no parent annotations.
+ */
+export function resolveAnnotationParents(spec: PColumnSpec): PColumnSpec {
+  const hasAnnotationParents = spec.axesSpec.some(
+    (axis) => !!readAnnotationJson(axis, Annotation.Parents),
+  );
+  if (!hasAnnotationParents) return spec;
+
+  const normalized = getNormalizedAxesList(spec.axesSpec);
+  const denormalized = getDenormalizedAxesList(normalized);
+  return { ...spec, axesSpec: denormalized };
+}
+
 /** Common type representing spec for all the axes in a column */
 export type AxesSpec = AxisSpec[];
 
@@ -706,7 +720,7 @@ export interface PColumnInfo extends PColumnIdAndSpec {
 export interface AxisId {
   /** Type of the axis or column value. For an axis should not use non-key
    * types like float or double. */
-  readonly type: ValueType;
+  readonly type: AxisValueType;
 
   /** Name of the axis or column */
   readonly name: string;

package/src/drivers/{pspec.ts → pframe/spec_driver.ts}

@@ -1,16 +1,28 @@
 import type { Branded } from "@milaboratories/helpers";
+import type { PoolEntry } from "../../pool_entry";
 import type {
-  ValueType,
-  SingleAxisSelector,
   AxisSpec,
+  AxesSpec,
+  AxesId,
   PColumnIdAndSpec,
   PColumnSpec,
-} from "./pframe";
-
-// --- Discover columns types (duplicated from middle-layer internal_api) ---
+  SingleAxisSelector,
+  AxisValueType,
+  ColumnValueType,
+} from "./spec";
+import type { PTableColumnId, PTableColumnSpec } from "./table_common";
+import { DataQuery, SpecQuery } from "./query";
 
 /** Matches a string value either exactly or by regex pattern */
-export type StringMatcher = { type: "exact"; value: string } | { type: "regex"; value: string };
+export type StringMatcher =
+  | {
+      type: "exact";
+      value: string;
+    }
+  | {
+      type: "regex";
+      value: string;
+    };
 
 /** Map of key to array of string matchers (OR-ed per key, AND-ed across keys) */
 export type MatcherMap = Record<string, StringMatcher[]>;
@@ -18,7 +30,7 @@ export type MatcherMap = Record<string, StringMatcher[]>;
 /** Selector for matching axes by various criteria */
 export interface MultiAxisSelector {
   /** Match any of the axis types listed here */
-  readonly type?: ValueType[];
+  readonly type?: AxisValueType[];
   /** Match any of the axis names listed here */
   readonly name?: StringMatcher[];
   /** Match requires all the domains listed here */
@@ -33,7 +45,7 @@ export interface MultiAxisSelector {
  * Multiple selectors are OR-ed: a column matches if it satisfies any selector. */
 export interface MultiColumnSelector {
   /** Match any of the value types listed here */
-  readonly type?: ValueType[];
+  readonly type?: ColumnValueType[];
   /** Match any of the names listed here */
   readonly name?: StringMatcher[];
   /** Match requires all the domains listed here */
@@ -78,10 +90,14 @@ export interface DiscoverColumnsConstraints {
 
 /** Request for discovering columns compatible with a given axes integration */
 export interface DiscoverColumnsRequest {
-  /** Column filters (OR-ed); empty array matches all columns */
-  columnFilter?: MultiColumnSelector[];
+  /** Include columns matching these selectors (OR-ed); empty or omitted matches all columns */
+  includeColumns?: MultiColumnSelector[];
+  /** Exclude columns matching these selectors (OR-ed); applied after include filter */
+  excludeColumns?: MultiColumnSelector[];
   /** Already integrated axes with qualifications */
   axes: ColumnAxesWithQualifications[];
+  /** Maximum number of hops allowed between provided axes integration and returned hits (0 = direct only) */
+  maxHops?: number;
   /** Constraints controlling axes matching and qualification behavior */
   constraints: DiscoverColumnsConstraints;
 }
@@ -120,6 +136,8 @@ export interface DiscoverColumnsResponseHit {
   hit: PColumnIdAndSpec;
   /** Possible ways to integrate this column with the existing set */
   mappingVariants: DiscoverColumnsMappingVariant[];
+  /** Linker steps traversed to reach this hit; empty for direct matches */
+  path: DiscoverColumnsStepInfo[];
 }
 
 /** Response from discover columns */
@@ -128,7 +146,32 @@ export interface DiscoverColumnsResponse {
   hits: DiscoverColumnsResponseHit[];
 }
 
-// --- Spec driver ---
+/** Request for deleting an entry from a given axes integration */
+export interface DeleteColumnRequest {
+  /** Already integrated axes with qualifications */
+  axes: ColumnAxesWithQualifications[];
+  /** Zero based index of the entry to be deleted */
+  delete: number;
+}
+
+/** Response from delete column */
+export interface DeleteColumnResponse {
+  axes: ColumnAxesWithQualifications[];
+}
+
+/** Response from evaluating a query against a PFrame. */
+export type EvaluateQueryResponse = {
+  /**
+   * The table specification describing the structure of the query result,
+   * including all axes and columns that will be present in the output.
+   */
+  tableSpec: PTableColumnSpec[];
+  /**
+   * The data layer query representation with numeric indices,
+   * suitable for execution by the data processing engine.
+   */
+  dataQuery: DataQuery;
+};
 
 /** Handle to a spec-only PFrame (no data, synchronous operations). */
 export type SpecFrameHandle = Branded<string, "SpecFrameHandle">;
@@ -140,16 +183,31 @@ export type SpecFrameHandle = Branded<string, "SpecFrameHandle">;
  * operates on column specifications only. All methods are synchronous
  * because the underlying WASM PFrame computes results immediately.
  */
-export interface PSpecDriver {
-  /** Create a spec-only PFrame from column specs. Returns a handle. */
-  createSpecFrame(specs: Record<string, PColumnSpec>): SpecFrameHandle;
+export interface PFrameSpecDriver {
+  /** Create a spec-only PFrame from column specs. Returns a pool entry with handle and unref. */
+  createSpecFrame(specs: Record<string, PColumnSpec>): PoolEntry<SpecFrameHandle>;
 
   /** Discover columns compatible with given axes integration. */
-  specFrameDiscoverColumns(
+  discoverColumns(
     handle: SpecFrameHandle,
     request: DiscoverColumnsRequest,
   ): DiscoverColumnsResponse;
 
-  /** Dispose a spec frame, freeing WASM resources. */
-  disposeSpecFrame(handle: SpecFrameHandle): void;
+  /** Delete an entry from a given axes integration */
+  deleteColumn(handle: SpecFrameHandle, request: DeleteColumnRequest): DeleteColumnResponse;
+
+  /** Evaluates a query specification against this PFrame */
+  evaluateQuery(handle: SpecFrameHandle, request: SpecQuery): EvaluateQueryResponse;
+
+  /** Expand index-based parentAxes in AxesSpec to resolved AxisId parents in AxesId. */
+  expandAxes(spec: AxesSpec): AxesId;
+
+  /** Collapse resolved AxisId parents back to index-based parentAxes in AxesSpec. */
+  collapseAxes(ids: AxesId): AxesSpec;
+
+  /** Find the index of an axis matching the given selector. Returns -1 if not found. */
+  findAxis(spec: AxesSpec, selector: SingleAxisSelector): number;
+
+  /** Find the flat index of a table column matching the given selector. Returns -1 if not found. */
+  findTableColumn(tableSpec: PTableColumnSpec[], selector: PTableColumnId): number;
 }

package/src/errors.ts

@@ -28,6 +28,59 @@ export function isAggregateError(error: unknown): error is AggregateError {
   return error instanceof Error && error.name === "AggregateError";
 }
 
+export class ServiceError extends Error {
+  name = "ServiceError";
+}
+
+export function isServiceError(error: unknown): error is ServiceError {
+  return (
+    error instanceof Error &&
+    (error.name === "ServiceError" || error.name.startsWith("ServiceError."))
+  );
+}
+
+export class ServiceInvalidIdError extends ServiceError {
+  name = "ServiceError.InvalidId";
+}
+
+export function isServiceInvalidIdError(error: unknown): error is ServiceInvalidIdError {
+  return error instanceof Error && error.name === "ServiceError.InvalidId";
+}
+
+export class ServiceAlreadyRegisteredError extends ServiceError {
+  name = "ServiceError.AlreadyRegistered";
+}
+
+export function isServiceAlreadyRegisteredError(
+  error: unknown,
+): error is ServiceAlreadyRegisteredError {
+  return error instanceof Error && error.name === "ServiceError.AlreadyRegistered";
+}
+
+export class ServiceInjectionError extends ServiceError {
+  name = "ServiceError.Injection";
+}
+
+export function isServiceInjectionError(error: unknown): error is ServiceInjectionError {
+  return error instanceof Error && error.name === "ServiceError.Injection";
+}
+
+export class ServiceNotRegisteredError extends ServiceError {
+  name = "ServiceError.NotRegistered";
+}
+
+export function isServiceNotRegisteredError(error: unknown): error is ServiceNotRegisteredError {
+  return error instanceof Error && error.name === "ServiceError.NotRegistered";
+}
+
+export class ServiceMethodNotFoundError extends ServiceError {
+  name = "ServiceError.MethodNotFound";
+}
+
+export function isServiceMethodNotFoundError(error: unknown): error is ServiceMethodNotFoundError {
+  return error instanceof Error && error.name === "ServiceError.MethodNotFound";
+}
+
 export class PFrameError extends Error {
   name = "PFrameError";
 }
@@ -44,6 +97,14 @@ export function isPFrameDriverError(error: unknown): error is PFrameDriverError
   return error instanceof Error && error.name === "PFrameError.Driver";
 }
 
+export class PFrameSpecDriverError extends PFrameError {
+  name = "PFrameError.SpecDriver";
+}
+
+export function isPFrameSpecDriverError(error: unknown): error is PFrameSpecDriverError {
+  return error instanceof Error && error.name === "PFrameError.SpecDriver";
+}
+
 function stringifyValue(value: unknown): string {
   if (typeof value === "string") {
     return `String value was thrown: ${value}`;

package/src/flags/block_flags.ts

@@ -1,3 +1,4 @@
+import type { ServiceRequireFlags } from "../services";
 import type { ArrayTypeUnion, Assert, Is, IsSubtypeOf } from "./type_utils";
 
 /**
@@ -20,7 +21,7 @@ export type BlockCodeKnownFeatureFlags = {
   readonly requiresModelAPIVersion?: number;
   readonly requiresUIAPIVersion?: number;
   readonly requiresCreatePTable?: number;
-};
+} & ServiceRequireFlags;
 
 export const AllSupportsFeatureFlags = ["supportsLazyState", "supportsPframeQueryRanking"] as const;
 
@@ -42,9 +43,11 @@ type _KnownFlagsAreValidFlags = Assert<
 
 // This check ensures that all keys in BlockConfigV3FeatureFlags are covered in the arrays above.
 // It will produce a compile-time error if there's a mismatch.
+// Adding a service to Services automatically satisfies this assertion via ServiceRequireFlags.
 type _AllFlagsAreCovered = Assert<
   Is<
     keyof BlockCodeKnownFeatureFlags,
-    ArrayTypeUnion<typeof AllRequiresFeatureFlags, typeof AllSupportsFeatureFlags>
+    | ArrayTypeUnion<typeof AllRequiresFeatureFlags, typeof AllSupportsFeatureFlags>
+    | keyof ServiceRequireFlags
   >
 >;

package/src/index.ts

@@ -18,3 +18,5 @@ export * from "./base64";
 export * from "./util";
 export * from "./httpAuth";
 export * from "./resource_types";
+export * from "./services";
+export * from "./pool_entry";

package/src/pool_entry.ts

@@ -0,0 +1,42 @@
+export interface PoolEntry<K extends string = string, R extends {} = {}> extends Disposable {
+  /** Resource key, calculated using provided `calculateParamsKey` function */
+  readonly key: K;
+
+  /** Resource itself created by `createNewResource` function */
+  readonly resource: R;
+
+  /**
+   * Release the reference. Idempotent.
+   * Same as `[Symbol.dispose]()` — provided as a named function
+   * for use in callbacks (e.g. `addOnDestroy(entry.unref)`).
+   */
+  readonly unref: () => void;
+}
+
+/**
+ * Wraps a PoolEntry for use with `using`. Auto-calls `unref()` at end of scope
+ * unless `keep()` is called to transfer ownership to the caller.
+ */
+export class PoolEntryGuard<K extends string = string, R extends {} = {}> implements Disposable {
+  private kept = false;
+
+  constructor(readonly entry: PoolEntry<K, R>) {}
+
+  get key(): K {
+    return this.entry.key;
+  }
+
+  get resource(): R {
+    return this.entry.resource;
+  }
+
+  /** Disarm the guard — caller takes ownership of the entry. */
+  keep(): PoolEntry<K, R> {
+    this.kept = true;
+    return this.entry;
+  }
+
+  [Symbol.dispose](): void {
+    if (!this.kept) this.entry.unref();
+  }
+}

package/src/services/index.ts

@@ -0,0 +1,5 @@
+export * from "./service_types";
+export * from "./service_registry";
+export * from "./service_declarations";
+export * from "./service_capabilities";
+export * from "./service_injectors";

package/src/services/service_capabilities.test.ts

@@ -0,0 +1,119 @@
+import { describe, it, expect, vi } from "vitest";
+import {
+  SERVICE_CAPABILITY_FLAGS,
+  registerServiceCapabilities,
+  resolveRequiredServices,
+  getMethodNames,
+  isKnownServiceName,
+} from "./service_capabilities";
+import { Services } from "./service_declarations";
+
+describe("SERVICE_CAPABILITY_FLAGS", () => {
+  it("should have one flag per service", () => {
+    expect(SERVICE_CAPABILITY_FLAGS).toHaveLength(Object.keys(Services).length);
+  });
+
+  it("should derive requires* flag names from Services keys", () => {
+    for (const key of Object.keys(Services)) {
+      expect(SERVICE_CAPABILITY_FLAGS).toContain(`requires${key}`);
+    }
+  });
+});
+
+describe("registerServiceCapabilities", () => {
+  it("should call register once per service with (flag, true)", () => {
+    const register = vi.fn();
+    registerServiceCapabilities(register);
+    expect(register).toHaveBeenCalledTimes(Object.keys(Services).length);
+    for (const call of register.mock.calls) {
+      expect(call[0]).toMatch(/^requires[A-Z]/);
+      expect(call[1]).toBe(true);
+    }
+  });
+});
+
+describe("resolveRequiredServices", () => {
+  it("should return empty array for undefined flags", () => {
+    expect(resolveRequiredServices(undefined)).toEqual([]);
+  });
+
+  it("should return empty array for flags without requires*", () => {
+    expect(resolveRequiredServices({ supportsLazyState: true })).toEqual([]);
+  });
+
+  it("should return empty array when requires* is false", () => {
+    expect(resolveRequiredServices({ requiresPFrameSpec: false })).toEqual([]);
+  });
+
+  it("should resolve a single required service", () => {
+    const result = resolveRequiredServices({ requiresPFrameSpec: true });
+    expect(result).toEqual([Services.PFrameSpec]);
+  });
+
+  it("should resolve multiple required services", () => {
+    const result = resolveRequiredServices({
+      requiresPFrameSpec: true,
+      requiresPFrame: true,
+    });
+    expect(result).toContain(Services.PFrameSpec);
+    expect(result).toContain(Services.PFrame);
+    expect(result).toHaveLength(2);
+  });
+
+  it("should ignore non-boolean requires* values", () => {
+    const result = resolveRequiredServices({
+      requiresPFrameSpec: true,
+      requiresModelAPIVersion: 2,
+    });
+    expect(result).toEqual([Services.PFrameSpec]);
+  });
+});
+
+describe("isKnownServiceName", () => {
+  it("should return true for registered service names", () => {
+    for (const id of Object.values(Services)) {
+      expect(isKnownServiceName(id as string)).toBe(true);
+    }
+  });
+
+  it("should return false for unknown names", () => {
+    expect(isKnownServiceName("nonexistent")).toBe(false);
+  });
+});
+
+describe("getMethodNames", () => {
+  it("should return own method names", () => {
+    const obj = {
+      foo() {},
+      bar() {},
+      baz: 42,
+    };
+    const names = getMethodNames(obj as any);
+    expect(names).toContain("foo");
+    expect(names).toContain("bar");
+    expect(names).not.toContain("baz");
+  });
+
+  it("should include prototype methods", () => {
+    class Base {
+      baseMethod() {}
+    }
+    class Child extends Base {
+      childMethod() {}
+    }
+    const names = getMethodNames(new Child() as any);
+    expect(names).toContain("baseMethod");
+    expect(names).toContain("childMethod");
+    expect(names).not.toContain("constructor");
+  });
+
+  it("should not include getters", () => {
+    const obj = Object.create(null, {
+      method: { value: () => {}, enumerable: true },
+      getter: { get: () => 42, enumerable: true },
+    });
+    const names = getMethodNames(obj);
+    expect(names).toContain("method");
+    expect(names).not.toContain("getter");
+  });
+});

package/src/services/service_capabilities.ts

@@ -0,0 +1,64 @@
+import type { ServiceName, ServiceRequireFlags } from "./service_types";
+import { Services } from "./service_declarations";
+import type { SupportedRequirement } from "../flags/flag_utils";
+
+/**
+ * All service-related `requires*` capability flag names, auto-derived from Services.
+ * Single source of truth — use this everywhere runtime capabilities are registered.
+ */
+export const SERVICE_CAPABILITY_FLAGS: readonly SupportedRequirement[] = Object.keys(Services).map(
+  (key) => `requires${key}` as SupportedRequirement,
+);
+
+/**
+ * Register all service capability flags with the given callback.
+ * Works with both `RuntimeCapabilities.addSupportedRequirement`
+ * and `MiddleLayer.addRuntimeCapability`.
+ */
+export function registerServiceCapabilities(
+  register: (flag: SupportedRequirement, value: true) => void,
+): void {
+  for (const flag of SERVICE_CAPABILITY_FLAGS) {
+    register(flag, true);
+  }
+}
+
+/**
+ * Resolve which services are required by the given feature flags.
+ * Accepts Record<string, unknown> so it works with both BlockCodeKnownFeatureFlags
+ * (from middle layer) and Zod-parsed records (from preload).
+ */
+export function resolveRequiredServices(flags: Record<string, unknown> | undefined): ServiceName[] {
+  if (!flags) return [];
+  return (Object.keys(Services) as (keyof typeof Services)[])
+    .filter((key) => flags[`requires${key}`] === true)
+    .map((key) => Services[key]);
+}
+
+export type KnownServiceName = (typeof Services)[keyof typeof Services] & string;
+
+export function isKnownServiceName(name: string): name is KnownServiceName {
+  return Object.values(Services).some((v) => v === name);
+}
+
+/** All service require flags set to true, auto-generated from Services.
+ *  Used to distinguish service-related feature flags from non-service flags. */
+export const SERVICE_FEATURE_FLAGS: { readonly [K in keyof ServiceRequireFlags]-?: true } =
+  Object.fromEntries(Object.keys(Services).map((key) => [`requires${key}`, true])) as any;
+
+/** Introspect method names on an instance (including prototype chain).
+ *  Uses Object.getOwnPropertyDescriptor to avoid triggering getters. */
+export function getMethodNames<T extends object>(instance: T): string[] {
+  const methods = new Set<string>();
+  let proto: object | null = instance;
+  while (proto && proto !== Object.prototype) {
+    for (const key of Object.getOwnPropertyNames(proto)) {
+      const descriptor = Object.getOwnPropertyDescriptor(proto, key);
+      if (key !== "constructor" && typeof descriptor?.value === "function") {
+        methods.add(key);
+      }
+    }
+    proto = Object.getPrototypeOf(proto);
+  }
+  return [...methods];
+}