constructa-core 0.0.6 → 0.1.0

package/README.md

@@ -6,7 +6,7 @@ This package contains the core runtime responsible for registering, composing, a
 
 ## Responsibilities
 
-Planned areas include:
+Current APIs define trusted generator implementations, portable typed definitions, and engine-provided generation context services. Planned areas include:
 
 * Generator registry
 * Generator execution
@@ -15,6 +15,12 @@ Planned areas include:
 * Generator composition and lifecycle
 * Structured errors
 
+## Generator implementation contract
+
+Use `defineGenerator()` for developer-authored executable implementations. An implementation declares a stable lowercase `type`, positive integer `version`, definition validator, optional dependency analysis hook, and `generate({ definition, context })` function. Validation returns schema `ValidationIssue` objects without imposing a validation-library dependency.
+
+`GeneratorDefinition<Output>` carries output information only at compile time; emitted definitions remain plain JSON data. Factories should use `createGeneratorDefinition()` so literal fields are preserved and the resulting definition is portable. Implementations receive randomness and child generation through `GenerationContext`; they must not use global randomness or built-in-specific execution switches.
+
 ## Dependency Boundary
 
 `constructa-schema` is the only Constructa runtime dependency that `constructa-core` may depend on.

package/dist/index.d.ts

@@ -1 +1,44 @@
-export {}
+import { GeneratorDefinition, GeneratorDefinition as GeneratorDefinition$1, Infer, ValidationIssue, ValidationIssue as ValidationIssue$1, ValidationPath, ValidationPath as ValidationPath$1 } from "constructa-schema";
+//#region src/index.d.ts
+type RandomSource = {
+  next(): number;
+};
+/** Services supplied by the engine. Implementations must not use global randomness. */
+type GenerationContext = {
+  readonly random: RandomSource;
+  readonly generateChild: <Output>(definition: GeneratorDefinition$1<Output>) => Output;
+};
+type GeneratorDependency = {
+  readonly typeId: string;
+  readonly path: ValidationPath$1;
+};
+type GeneratorImplementation<Definition extends GeneratorDefinition$1<Output>, Output> = {
+  readonly type: string;
+  readonly version: number;
+  readonly validateDefinition: (definition: unknown) => readonly ValidationIssue$1[];
+  readonly analyzeDependencies?: (definition: Definition) => readonly GeneratorDependency[];
+  readonly generate: (input: {
+    readonly definition: Definition;
+    readonly context: GenerationContext;
+  }) => Output;
+};
+/**
+ * Defines a trusted, developer-authored generator implementation. This API has
+ * no dependency on a particular validation library.
+ */
+declare function defineGenerator<const Definition extends GeneratorDefinition$1<Output>, Output>(implementation: GeneratorImplementation<Definition, Output>): GeneratorImplementation<Definition, Output>;
+/** Builds a portable definition while preserving literal fields and output inference. */
+declare function createGeneratorDefinition<Output, const Definition extends GeneratorDefinition$1<Output>>(definition: Definition): Definition;
+/**
+ * Invokes one validated implementation. Registry lookup and dispatch are added
+ * later; this function keeps validation and execution failure normalization in
+ * the same shared contract today.
+ */
+declare function invokeGeneratorImplementation<Definition extends GeneratorDefinition$1<Output>, Output>(implementation: GeneratorImplementation<Definition, Output>, input: {
+  readonly definition: Definition;
+  readonly context: GenerationContext;
+  readonly path?: ValidationPath$1;
+}): Output;
+//#endregion
+export { GenerationContext, type GeneratorDefinition, GeneratorDependency, GeneratorImplementation, type Infer, RandomSource, type ValidationIssue, type ValidationPath, createGeneratorDefinition, defineGenerator, invokeGeneratorImplementation };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"mappings":";;KAgBY;EACV;;;KAIU;WACD,QAAQ;WACR,gBAAgB,QACvB,YAAY,sBAAoB,YAC7B;;KAGK;WACD;WACA,MAAM;;KAGL,wBACV,mBAAmB,sBAAoB,SACvC;WAES;WACA;WACA,qBACP,iCACY;WACL,uBACP,YAAY,wBACA;WACL,WAAW;aACT,YAAY;aACZ,SAAS;QACd;;;;;;iBAOQ,sBACR,mBAAmB,sBAAoB,SAC7C,QAEA,gBAAgB,wBAAwB,YAAY,UACnD,wBAAwB,YAAY;;iBAMvB,0BACd,cACM,mBAAmB,sBAAoB,SAC7C,YAAY,aAAa;;;;;;iBAUX,8BACd,mBAAmB,sBAAoB,SACvC,QAEA,gBAAgB,wBAAwB,YAAY,SACpD;WACW,YAAY;WACZ,SAAS;WACT,OAAO;IAEjB"}

package/dist/index.js

@@ -0,0 +1,77 @@
+import { ConstructaError, assertGeneratorDefinition, normalizeConstructaError } from "constructa-schema";
+//#region src/index.ts
+/**
+* Defines a trusted, developer-authored generator implementation. This API has
+* no dependency on a particular validation library.
+*/
+function defineGenerator(implementation) {
+	assertGeneratorImplementation(implementation);
+	return implementation;
+}
+/** Builds a portable definition while preserving literal fields and output inference. */
+function createGeneratorDefinition(definition) {
+	assertGeneratorDefinition(definition);
+	return definition;
+}
+/**
+* Invokes one validated implementation. Registry lookup and dispatch are added
+* later; this function keeps validation and execution failure normalization in
+* the same shared contract today.
+*/
+function invokeGeneratorImplementation(implementation, input) {
+	const path = input.path ?? [];
+	let issues;
+	try {
+		issues = implementation.validateDefinition(input.definition);
+	} catch (cause) {
+		throw normalizeConstructaError(cause, {
+			kind: "configuration",
+			code: "INVALID_CONFIGURATION",
+			path,
+			message: "Generator definition validation failed."
+		});
+	}
+	if (issues.length > 0) {
+		const [issue] = issues;
+		if (issue !== void 0) throw new ConstructaError({
+			kind: "configuration",
+			code: "INVALID_CONFIGURATION",
+			path: [...path, ...issue.path],
+			message: issue.message,
+			details: { issueCode: issue.code }
+		});
+		throw new ConstructaError({
+			kind: "system",
+			code: "EXECUTION_FAILED",
+			path,
+			message: "Generator validation returned an invalid result."
+		});
+	}
+	try {
+		return implementation.generate({
+			definition: input.definition,
+			context: input.context
+		});
+	} catch (cause) {
+		throw normalizeConstructaError(cause, {
+			kind: "execution",
+			code: "EXECUTION_FAILED",
+			path,
+			message: "Generator execution failed."
+		});
+	}
+}
+function assertGeneratorImplementation(implementation) {
+	if (!isStableTypeId(implementation.type)) throw new TypeError("generator type must be a stable lowercase identifier");
+	if (!Number.isSafeInteger(implementation.version) || implementation.version < 1) throw new TypeError("generator version must be a positive safe integer");
+	if (typeof implementation.validateDefinition !== "function") throw new TypeError("validateDefinition must be a function");
+	if (typeof implementation.generate !== "function") throw new TypeError("generate must be a function");
+	if (implementation.analyzeDependencies !== void 0 && typeof implementation.analyzeDependencies !== "function") throw new TypeError("analyzeDependencies must be a function when present");
+}
+function isStableTypeId(value) {
+	return /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/u.test(value);
+}
+//#endregion
+export { createGeneratorDefinition, defineGenerator, invokeGeneratorImplementation };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["import {\n  assertGeneratorDefinition,\n  ConstructaError,\n  type GeneratorDefinition,\n  normalizeConstructaError,\n  type ValidationIssue,\n  type ValidationPath,\n} from \"constructa-schema\";\n\nexport type {\n  GeneratorDefinition,\n  Infer,\n  ValidationIssue,\n  ValidationPath,\n} from \"constructa-schema\";\n\nexport type RandomSource = {\n  next(): number;\n};\n\n/** Services supplied by the engine. Implementations must not use global randomness. */\nexport type GenerationContext = {\n  readonly random: RandomSource;\n  readonly generateChild: <Output>(\n    definition: GeneratorDefinition<Output>,\n  ) => Output;\n};\n\nexport type GeneratorDependency = {\n  readonly typeId: string;\n  readonly path: ValidationPath;\n};\n\nexport type GeneratorImplementation<\n  Definition extends GeneratorDefinition<Output>,\n  Output,\n> = {\n  readonly type: string;\n  readonly version: number;\n  readonly validateDefinition: (\n    definition: unknown,\n  ) => readonly ValidationIssue[];\n  readonly analyzeDependencies?: (\n    definition: Definition,\n  ) => readonly GeneratorDependency[];\n  readonly generate: (input: {\n    readonly definition: Definition;\n    readonly context: GenerationContext;\n  }) => Output;\n};\n\n/**\n * Defines a trusted, developer-authored generator implementation. This API has\n * no dependency on a particular validation library.\n */\nexport function defineGenerator<\n  const Definition extends GeneratorDefinition<Output>,\n  Output,\n>(\n  implementation: GeneratorImplementation<Definition, Output>,\n): GeneratorImplementation<Definition, Output> {\n  assertGeneratorImplementation(implementation);\n  return implementation;\n}\n\n/** Builds a portable definition while preserving literal fields and output inference. */\nexport function createGeneratorDefinition<\n  Output,\n  const Definition extends GeneratorDefinition<Output>,\n>(definition: Definition): Definition {\n  assertGeneratorDefinition(definition);\n  return definition;\n}\n\n/**\n * Invokes one validated implementation. Registry lookup and dispatch are added\n * later; this function keeps validation and execution failure normalization in\n * the same shared contract today.\n */\nexport function invokeGeneratorImplementation<\n  Definition extends GeneratorDefinition<Output>,\n  Output,\n>(\n  implementation: GeneratorImplementation<Definition, Output>,\n  input: {\n    readonly definition: Definition;\n    readonly context: GenerationContext;\n    readonly path?: ValidationPath;\n  },\n): Output {\n  const path = input.path ?? [];\n  let issues: readonly ValidationIssue[];\n\n  try {\n    issues = implementation.validateDefinition(input.definition);\n  } catch (cause) {\n    throw normalizeConstructaError(cause, {\n      kind: \"configuration\",\n      code: \"INVALID_CONFIGURATION\",\n      path,\n      message: \"Generator definition validation failed.\",\n    });\n  }\n\n  if (issues.length > 0) {\n    const [issue] = issues;\n    if (issue !== undefined) {\n      throw new ConstructaError({\n        kind: \"configuration\",\n        code: \"INVALID_CONFIGURATION\",\n        path: [...path, ...issue.path],\n        message: issue.message,\n        details: { issueCode: issue.code },\n      });\n    }\n\n    throw new ConstructaError({\n      kind: \"system\",\n      code: \"EXECUTION_FAILED\",\n      path,\n      message: \"Generator validation returned an invalid result.\",\n    });\n  }\n\n  try {\n    return implementation.generate({\n      definition: input.definition,\n      context: input.context,\n    });\n  } catch (cause) {\n    throw normalizeConstructaError(cause, {\n      kind: \"execution\",\n      code: \"EXECUTION_FAILED\",\n      path,\n      message: \"Generator execution failed.\",\n    });\n  }\n}\n\nfunction assertGeneratorImplementation(implementation: {\n  readonly type: string;\n  readonly version: number;\n  readonly validateDefinition: unknown;\n  readonly analyzeDependencies?: unknown;\n  readonly generate: unknown;\n}): void {\n  if (!isStableTypeId(implementation.type)) {\n    throw new TypeError(\"generator type must be a stable lowercase identifier\");\n  }\n  if (\n    !Number.isSafeInteger(implementation.version) ||\n    implementation.version < 1\n  ) {\n    throw new TypeError(\"generator version must be a positive safe integer\");\n  }\n  if (typeof implementation.validateDefinition !== \"function\") {\n    throw new TypeError(\"validateDefinition must be a function\");\n  }\n  if (typeof implementation.generate !== \"function\") {\n    throw new TypeError(\"generate must be a function\");\n  }\n  if (\n    implementation.analyzeDependencies !== undefined &&\n    typeof implementation.analyzeDependencies !== \"function\"\n  ) {\n    throw new TypeError(\"analyzeDependencies must be a function when present\");\n  }\n}\n\nfunction isStableTypeId(value: string): boolean {\n  return /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/u.test(value);\n}\n"],"mappings":";;;;;;AAuDA,SAAgB,gBAId,gBAC6C;CAC7C,8BAA8B,cAAc;CAC5C,OAAO;AACT;;AAGA,SAAgB,0BAGd,YAAoC;CACpC,0BAA0B,UAAU;CACpC,OAAO;AACT;;;;;;AAOA,SAAgB,8BAId,gBACA,OAKQ;CACR,MAAM,OAAO,MAAM,QAAQ,CAAC;CAC5B,IAAI;CAEJ,IAAI;EACF,SAAS,eAAe,mBAAmB,MAAM,UAAU;CAC7D,SAAS,OAAO;EACd,MAAM,yBAAyB,OAAO;GACpC,MAAM;GACN,MAAM;GACN;GACA,SAAS;EACX,CAAC;CACH;CAEA,IAAI,OAAO,SAAS,GAAG;EACrB,MAAM,CAAC,SAAS;EAChB,IAAI,UAAU,KAAA,GACZ,MAAM,IAAI,gBAAgB;GACxB,MAAM;GACN,MAAM;GACN,MAAM,CAAC,GAAG,MAAM,GAAG,MAAM,IAAI;GAC7B,SAAS,MAAM;GACf,SAAS,EAAE,WAAW,MAAM,KAAK;EACnC,CAAC;EAGH,MAAM,IAAI,gBAAgB;GACxB,MAAM;GACN,MAAM;GACN;GACA,SAAS;EACX,CAAC;CACH;CAEA,IAAI;EACF,OAAO,eAAe,SAAS;GAC7B,YAAY,MAAM;GAClB,SAAS,MAAM;EACjB,CAAC;CACH,SAAS,OAAO;EACd,MAAM,yBAAyB,OAAO;GACpC,MAAM;GACN,MAAM;GACN;GACA,SAAS;EACX,CAAC;CACH;AACF;AAEA,SAAS,8BAA8B,gBAM9B;CACP,IAAI,CAAC,eAAe,eAAe,IAAI,GACrC,MAAM,IAAI,UAAU,sDAAsD;CAE5E,IACE,CAAC,OAAO,cAAc,eAAe,OAAO,KAC5C,eAAe,UAAU,GAEzB,MAAM,IAAI,UAAU,mDAAmD;CAEzE,IAAI,OAAO,eAAe,uBAAuB,YAC/C,MAAM,IAAI,UAAU,uCAAuC;CAE7D,IAAI,OAAO,eAAe,aAAa,YACrC,MAAM,IAAI,UAAU,6BAA6B;CAEnD,IACE,eAAe,wBAAwB,KAAA,KACvC,OAAO,eAAe,wBAAwB,YAE9C,MAAM,IAAI,UAAU,qDAAqD;AAE7E;AAEA,SAAS,eAAe,OAAwB;CAC9C,OAAO,uCAAuC,KAAK,KAAK;AAC1D"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "constructa-core",
-  "version": "0.0.6",
+  "version": "0.1.0",
   "description": "The UI-agnostic Constructa generator execution engine.",
   "private": false,
   "license": "MIT",
@@ -26,7 +26,7 @@
     "access": "public"
   },
   "dependencies": {
-    "constructa-schema": "2.0.0"
+    "constructa-schema": "2.2.0"
   },
   "devDependencies": {
     "typescript": "^6.0.3",