flow-step-space-logic 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flow-step-space-logic",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "private": false,
   "description": "Exact explicit-ref StepSpace loading, normalization, and profile assembly",
   "type": "module",
@@ -10,7 +10,7 @@
     "./filesystem": "./src/filesystem.ts"
   },
   "dependencies": {
-    "flow-step-space-contract": "0.1.0",
+    "flow-step-space-contract": "0.1.1",
     "xnl-core": "^0.1.8"
   },
   "files": [

package/src/filesystem.ts

@@ -11,6 +11,19 @@ import {
 export interface FilesystemDefinitionStepRuntimeOptions {
   /** Host policy lives in the runtime adapter, never in semantic Processor input. */
   readonly rootDir: string;
+  readonly extensionCodecs?: DefinitionStepAssemblyRuntime['extensionCodecs'];
+}
+
+export interface FilesystemDefinitionStepProfileRuntime extends DefinitionStepAssemblyRuntime {
+  readonly profileSources: {
+    readTopLevelXnlSources(): readonly { readonly ref: string; readonly content: string }[];
+  };
+}
+
+export interface AssembleDefinitionStepProfileDirectoryInput {}
+
+export interface AssembleDefinitionStepProfileDirectoryConfig extends DefinitionStepProfileLoadOptions {
+  readonly profileRoot: string;
 }
 
 export function createFilesystemDefinitionStepRuntime(
@@ -46,30 +59,59 @@ export function createFilesystemDefinitionStepRuntime(
         return new Uint8Array(fs.readFileSync(realFile));
       },
     }),
+    extensionCodecs: options.extensionCodecs ?? Object.freeze({ resolve: () => undefined }),
   });
 }
 
-/** Reads only top-level profile/facet files, then follows the exact declared closure. */
+export function createFilesystemDefinitionStepProfileRuntime(
+  options: FilesystemDefinitionStepRuntimeOptions,
+): FilesystemDefinitionStepProfileRuntime {
+  const absoluteRoot = path.resolve(options.rootDir);
+  const stepRuntime = createFilesystemDefinitionStepRuntime(options);
+  return Object.freeze({
+    ...stepRuntime,
+    profileSources: Object.freeze({
+      readTopLevelXnlSources() {
+        return fs.readdirSync(absoluteRoot, { withFileTypes: true })
+          .filter((entry) => entry.isFile() && entry.name.endsWith('.xnl'))
+          .sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0)
+          .map((entry) => Object.freeze({
+            ref: entry.name,
+            content: fs.readFileSync(path.join(absoluteRoot, entry.name), 'utf8'),
+          }));
+      },
+    }),
+  });
+}
+
+/** Processor authority; the host root is closed inside the runtime adapter. */
 export function assembleDefinitionStepProfileDirectory(
+  runtime: FilesystemDefinitionStepProfileRuntime,
+  _input: AssembleDefinitionStepProfileDirectoryInput,
+  config: AssembleDefinitionStepProfileDirectoryConfig,
+) {
+  if (!runtime?.profileSources || typeof runtime.profileSources.readTopLevelXnlSources !== 'function') {
+    throw diagnostic('step-profile-runtime-invalid', 'runtime.profileSources.readTopLevelXnlSources is required');
+  }
+  const sources = runtime.profileSources.readTopLevelXnlSources();
+  return assembleDefinitionStepProfileSourcesWithRuntime(
+    { sources: runtime.sources, extensionCodecs: runtime.extensionCodecs },
+    sources,
+    config.profileRoot,
+    config,
+  );
+}
+
+/** @deprecated Compatibility wrapper; new code must inject a filesystem runtime. */
+export function assembleDefinitionStepProfileDirectoryFromRoot(
   rootDir: string,
   profileRoot: string,
   options: DefinitionStepProfileLoadOptions = {},
 ) {
-  const absoluteRoot = path.resolve(rootDir);
-  const sources = fs.existsSync(absoluteRoot)
-    ? fs.readdirSync(absoluteRoot, { withFileTypes: true })
-        .filter((entry) => entry.isFile() && entry.name.endsWith('.xnl'))
-        .sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0)
-        .map((entry) => ({
-          name: entry.name,
-          content: fs.readFileSync(path.join(absoluteRoot, entry.name), 'utf8'),
-        }))
-    : [];
-  return assembleDefinitionStepProfileSourcesWithRuntime(
-    createFilesystemDefinitionStepRuntime({ rootDir: absoluteRoot }),
-    sources,
-    profileRoot,
-    options,
+  return assembleDefinitionStepProfileDirectory(
+    createFilesystemDefinitionStepProfileRuntime({ rootDir }),
+    {},
+    { ...options, profileRoot },
   );
 }
 

package/src/index.ts

@@ -10,12 +10,19 @@ import type {
   DefinitionStepDiagnostic,
   DefinitionStepDigest,
   DefinitionStepExtension,
+  DefinitionStepExtensionRegistration,
   DefinitionStepForest,
   DefinitionStepForestNode,
   DefinitionStepGroup,
   DefinitionStepProfileLoadOptions,
+  DefinitionStepProfileAssemblyConfig,
+  DefinitionStepProfileAssemblyInput,
   DefinitionStepSourceCollection,
   DefinitionStepSourceRef,
+  DefinitionStepMutationConfig,
+  DefinitionStepMutationInvocation,
+  DefinitionStepMutationRuntime,
+  DefinitionStepSelector,
   DefinitionStepValue,
   ImmutableStepRecord,
   StepMerkleDiff,
@@ -276,7 +283,6 @@ function nodeProjection(element: Element, sourceRef: string): DefinitionStepCore
 
 type AssemblyState = {
   readonly runtime: DefinitionStepAssemblyRuntime;
-  readonly config: DefinitionStepAssemblyConfig;
   readonly closure: DefinitionStepClosureEntry[];
   readonly closureByRef: Map<string, DefinitionStepClosureEntry>;
   readonly steps: Record<string, DefinitionStep>;
@@ -326,7 +332,7 @@ function readExtension(
   if (idOf(refElement)) fail('step-extension-ref-id-unsupported', 'ExtensionRef must not declare an id', undefined, stepId);
   const attrs = exactAttrs(refElement, ['kind', 'src', 'schema'], state.activeRefs.at(-1) ?? '');
   const kind = requiredString(attrs, 'kind', state.activeRefs.at(-1) ?? '');
-  const registration = state.config.extensions[kind];
+  const registration = resolveExtensionRegistration(state.runtime, kind);
   if (!registration) fail('step-extension-kind-undeclared', `extension kind ${kind} is not registered`, undefined, stepId);
   const ref = normalizeDefinitionStepSourceRef(requiredString(attrs, 'src', state.activeRefs.at(-1) ?? ''));
   const declaredSchema = attrs.schema;
@@ -350,12 +356,25 @@ function readExtension(
     }
     const extensionId = idOf(root);
     if (!extensionId) fail('step-extension-id-missing', `${ref} StepExtension requires an id`, ref, stepId);
+    const rawValue = closedValue(rootAttrs.value ?? null, `${ref}:value`);
+    let normalizedValue = rawValue;
+    try {
+      normalizedValue = closedValue(registration.codec.normalize(rawValue, {
+        kind,
+        ...(typeof declaredSchema === 'string' ? { schemaRef: declaredSchema } : {}),
+        sourceRef: ref,
+        stepId,
+      }), `${ref}:codec`);
+    } catch (error) {
+      if (error instanceof DefinitionStepAssemblyError) throw error;
+      fail('step-extension-codec-invalid', `${ref} codec rejected the extension: ${(error as Error).message}`, ref, stepId);
+    }
     return Object.freeze({
       id: extensionId,
       kind,
       sourceRef: ref,
       ...(typeof declaredSchema === 'string' ? { schemaRef: declaredSchema } : {}),
-      value: closedValue(rootAttrs.value ?? null, `${ref}:value`),
+      value: normalizedValue,
       digest: entry.digest,
     });
   });
@@ -443,37 +462,128 @@ function normalizeAssemblyBoundary(
   inputValue: DefinitionStepAssemblyInput,
   configValue: DefinitionStepAssemblyConfig,
 ) {
-  const runtime = exactOwnDataRecord(runtimeValue, ['sources'], 'runtime');
+  const runtime = exactOwnDataRecord(runtimeValue, ['sources', 'extensionCodecs'], 'runtime');
   const sources = exactOwnDataRecord(ownValue(runtime, 'sources'), ['readSource'], 'runtime.sources');
   if (typeof ownValue(sources, 'readSource') !== 'function') fail('step-runtime-invalid', 'runtime.sources.readSource must be a function');
-  const input = exactOwnDataRecord(inputValue, ['stepSpaceRef'], 'input');
-  const config = exactOwnDataRecord(configValue, ['extensions'], 'config');
-  const extensionRecord = exactOwnDataRecord(ownValue(config, 'extensions'), Object.keys(ownValue(config, 'extensions') as object), 'config.extensions');
-  for (const [kind, registrationValue] of Object.entries(extensionRecord)) {
-    if (!kind || kind !== kind.trim()) fail('step-extension-registration-invalid', 'extension kind must be an exact non-empty string');
-    const registration = exactOwnDataRecord(registrationValue, ['schemaRef'], `config.extensions.${kind}`);
-    const schemaRef = ownValue(registration, 'schemaRef');
-    if (schemaRef !== undefined && (typeof schemaRef !== 'string' || !schemaRef)) {
-      fail('step-extension-registration-invalid', `${kind}.schemaRef must be a non-empty string`);
-    }
+  const extensionCodecs = exactOwnDataRecord(ownValue(runtime, 'extensionCodecs'), ['resolve'], 'runtime.extensionCodecs');
+  if (typeof ownValue(extensionCodecs, 'resolve') !== 'function') {
+    fail('step-runtime-invalid', 'runtime.extensionCodecs.resolve must be a function');
   }
+  const input = exactOwnDataRecord(inputValue, ['stepSpaceRef'], 'input');
+  exactOwnDataRecord(configValue, [], 'config');
   return {
     runtime: runtimeValue,
     input: { stepSpaceRef: normalizeDefinitionStepSourceRef(ownValue(input, 'stepSpaceRef')) },
-    config: configValue,
   };
 }
 
+function resolveExtensionRegistration(
+  runtime: Pick<DefinitionStepAssemblyRuntime, 'extensionCodecs'> | Pick<DefinitionStepMutationRuntime, 'extensionCodecs'>,
+  kind: string,
+): DefinitionStepExtensionRegistration | undefined {
+  if (!kind || kind !== kind.trim()) fail('step-extension-registration-invalid', 'extension kind must be an exact non-empty string');
+  const registrationValue = runtime.extensionCodecs.resolve(kind);
+  if (registrationValue === undefined) return undefined;
+  const registration = exactOwnDataRecord(registrationValue, ['schemaRef', 'codec'], `runtime.extensionCodecs.${kind}`);
+  const schemaRef = ownValue(registration, 'schemaRef');
+  if (schemaRef !== undefined && (typeof schemaRef !== 'string' || !schemaRef)) {
+    fail('step-extension-registration-invalid', `${kind}.schemaRef must be a non-empty string`);
+  }
+  const codec = ownValue(registration, 'codec');
+  if (codec === undefined) fail('step-extension-registration-invalid', `${kind}.codec is required`);
+  const codecRecord = exactOwnDataRecord(codec, ['normalize'], `runtime.extensionCodecs.${kind}.codec`);
+  if (typeof ownValue(codecRecord, 'normalize') !== 'function') {
+    fail('step-extension-registration-invalid', `${kind}.codec.normalize must be a function`);
+  }
+  return registrationValue as DefinitionStepExtensionRegistration;
+}
+
+function normalizeRegisteredExtensionValue(
+  registration: DefinitionStepExtensionRegistration,
+  value: unknown,
+  context: { readonly kind: string; readonly sourceRef: string; readonly stepId: string },
+): DefinitionStepValue {
+  const closed = closedValue(value, `mutation.${context.stepId}.${context.kind}`);
+  try {
+    return closedValue(registration.codec.normalize(closed, {
+      ...context,
+      ...(registration.schemaRef ? { schemaRef: registration.schemaRef } : {}),
+    }), `mutation.${context.stepId}.${context.kind}.codec`);
+  } catch (error) {
+    if (error instanceof DefinitionStepAssemblyError) throw error;
+    fail('step-extension-codec-invalid', `${context.kind} codec rejected the mutation: ${(error as Error).message}`, context.sourceRef, context.stepId);
+  }
+}
+
+/** Targeted Processor form: output = fn(runtime, selector, invocation, config). */
+export function mutateDefinitionStep(
+  runtime: DefinitionStepMutationRuntime,
+  selector: DefinitionStepSelector,
+  invocation: DefinitionStepMutationInvocation,
+  config: DefinitionStepMutationConfig,
+): DefinitionStep {
+  if (!runtime || typeof runtime !== 'object'
+    || !runtime.steps || typeof runtime.steps.readStep !== 'function'
+    || typeof runtime.steps.writeStep !== 'function'
+    || !runtime.extensionCodecs || typeof runtime.extensionCodecs.resolve !== 'function') {
+    fail('step-mutation-runtime-invalid', 'runtime must provide steps and extensionCodecs ports');
+  }
+  exactOwnDataRecord(config, [], 'config');
+  if (!selector || typeof selector !== 'object' || typeof selector.stepId !== 'string'
+    || !selector.stepId || selector.stepId !== selector.stepId.trim()) {
+    fail('step-mutation-selector-invalid', 'selector.stepId must be an exact non-empty string');
+  }
+  const before = runtime.steps.readStep(selector.stepId);
+  if (!before) fail('step-mutation-target-missing', `step ${selector.stepId} does not exist`, undefined, selector.stepId);
+  if (invocation.expectedDigest !== before.digest) {
+    fail('step-mutation-version-conflict', `step ${selector.stepId} digest changed`, before.sourceRef, selector.stepId);
+  }
+  const extensions: Record<string, DefinitionStepExtension> = { ...before.extensions };
+  for (const [kind, value] of Object.entries(invocation.extensions ?? {})) {
+    const registration = resolveExtensionRegistration(runtime, kind);
+    const prior = before.extensions[kind];
+    if (!registration || !prior) {
+      fail('step-extension-kind-undeclared', `extension kind ${kind} is not admitted for step ${selector.stepId}`, before.sourceRef, selector.stepId);
+    }
+    if (!registration.codec || typeof registration.codec.normalize !== 'function') {
+      fail('step-extension-registration-invalid', `${kind}.codec.normalize is required for mutation`, before.sourceRef, selector.stepId);
+    }
+    if (registration.schemaRef !== prior.schemaRef) {
+      fail('step-extension-schema-mismatch', `${kind} mutation registry does not match the admitted schema`, before.sourceRef, selector.stepId);
+    }
+    const normalized = normalizeRegisteredExtensionValue(registration, value, {
+      kind,
+      sourceRef: prior.sourceRef,
+      stepId: selector.stepId,
+    });
+    extensions[kind] = Object.freeze({
+      ...prior,
+      value: normalized,
+      digest: digest(canonicalJson({ kind, schemaRef: prior.schemaRef ?? null, value: normalized })),
+    });
+  }
+  const core = invocation.core === undefined
+    ? before.core
+    : normalizeCore(invocation.core, `mutation.${selector.stepId}.core`);
+  const next = Object.freeze({
+    ...before,
+    core,
+    extensions: Object.freeze(extensions),
+    digest: digest(JSON.stringify({ id: before.id, core, extensions })),
+  });
+  runtime.steps.writeStep(next, before.digest);
+  return next;
+}
+
 /** Processor form: output = fn(runtime, input, config). */
 export function assembleDefinitionStepForest(
   runtimeValue: DefinitionStepAssemblyRuntime,
   inputValue: DefinitionStepAssemblyInput,
   configValue: DefinitionStepAssemblyConfig,
 ): DefinitionStepForest {
-  const { runtime, input, config } = normalizeAssemblyBoundary(runtimeValue, inputValue, configValue);
+  const { runtime, input } = normalizeAssemblyBoundary(runtimeValue, inputValue, configValue);
   const state: AssemblyState = {
     runtime,
-    config,
     closure: [],
     closureByRef: new Map(),
     steps: {},
@@ -652,6 +762,7 @@ export function normalizeDefinitionStepForest(value: unknown): DefinitionStepFor
 
 export function createDefinitionStepSourceRuntime(
   sources: CompatibleSourceCollection,
+  extensionCodecs: DefinitionStepAssemblyRuntime['extensionCodecs'] = Object.freeze({ resolve: () => undefined }),
 ): DefinitionStepAssemblyRuntime {
   const entries = Array.isArray(sources)
     ? sources.map((source) => ['ref' in source ? source.ref : source.name, source.content] as const)
@@ -672,6 +783,7 @@ export function createDefinitionStepSourceRuntime(
         return bytes.slice();
       },
     }),
+    extensionCodecs,
   });
 }
 
@@ -705,6 +817,20 @@ export interface DefinitionStepProfileAssemblyResult {
   readonly diagnostics: readonly DefinitionStepDiagnostic[];
 }
 
+/** Processor authority for profile composition: output = fn(runtime, input, config). */
+export function assembleDefinitionStepProfile(
+  runtime: DefinitionStepAssemblyRuntime,
+  input: DefinitionStepProfileAssemblyInput,
+  config: DefinitionStepProfileAssemblyConfig,
+): DefinitionStepProfileAssemblyResult {
+  return assembleDefinitionStepProfileSourcesWithRuntime(
+    runtime,
+    input.sources,
+    config.profileRoot,
+    config,
+  );
+}
+
 /**
  * Pure-source composition helper used by profile owners. It only recognizes the
  * exact profileSourceRef and follows the explicit StepSpace closure.
@@ -714,11 +840,13 @@ export function assembleDefinitionStepProfileSources(
   profileRoot: string,
   options: DefinitionStepProfileLoadOptions = {},
 ): DefinitionStepProfileAssemblyResult {
-  return assembleDefinitionStepProfileSourcesWithRuntime(
+  const normalizedSources: DefinitionStepSourceCollection = Array.isArray(sources)
+    ? sources.map((source) => ({ ref: 'ref' in source ? source.ref : source.name, content: source.content }))
+    : Object.entries(sources).map(([ref, content]) => ({ ref, content }));
+  return assembleDefinitionStepProfile(
     createDefinitionStepSourceRuntime(sources),
-    sources,
-    profileRoot,
-    options,
+    { sources: normalizedSources },
+    { ...options, profileRoot },
   );
 }
 
@@ -756,9 +884,9 @@ export function assembleDefinitionStepProfileSourcesWithRuntime(
       fail('step-space-ref-invalid', 'StepSpaceRef must contain only src', profileSourceRef);
     }
     const forest = assembleDefinitionStepForest(
-      runtime,
+      { sources: runtime.sources, extensionCodecs: runtime.extensionCodecs },
       { stepSpaceRef: requiredString(refAttrs, 'src', profileSourceRef) },
-      { extensions: options.extensions ?? {} },
+      {},
     );
     const retainedSections = sectionChildren(root).filter((section) => section.tag !== 'StepSpaceRef');
     const projectedRoot = {