@shapeshift-labs/frontier-lang-parser 0.3.17 → 0.3.18

package/README.md

@@ -239,6 +239,27 @@ conversion TodoJavascriptToRust @id("conversion_todo_js_rust") {
 
 `sourceRuntime` and `targetRuntime` become runtime maps. `runtimeRequirement` rows become proof obligations for host/runtime capabilities, including authored `requiredSignals` denominators such as source hashes, target hashes, probe ids, runtime commands, telemetry hashes, and capability-specific trace hashes. `proofEvidence` and `evidence` attach evidence ids, but the compiler still requires bound evidence records before a proof obligation is satisfied. `dialect` and `extern` rows preserve dialect-specific constructs, projection readiness, loss/evidence ids, and binding metadata without requiring the authored Frontier file to drop down to raw JSON.
 
+## Authored possibility spaces
+
+`.frontier` files can describe a governed space of valid implementations with `constraintSpace` or `possibilitySpace` blocks. These blocks are metadata-only: they do not add kernel nodes, but they preserve the variables, hard constraints, preferences, collapse strategies, and admission rules that let tools reason about semantic merge, translation, refactoring, and runtime projection as constraint satisfaction.
+
+```frontier
+possibilitySpace CheckoutSurface @id("space_checkout_surface") {
+  subject action_checkout
+  scope mod_checkout
+  target react
+  target swiftui
+  variable surface @id("space_variable_surface") kind projection domain react|swiftui|html-css-js default react preserve identity|event-flow
+  hard identity @id("space_constraint_identity") kind semantic-identity family identity subject action_checkout requires action|state|effect failClosed
+  soft bundleSize @id("space_constraint_bundle_size") kind bundle-budget family runtime target react predicate "bundle < 50kb"
+  preference nativeControls @id("space_preference_native_controls") kind platform-idiom target swiftui weight 0.8 reason "prefer native controls on iOS"
+  collapse mobileCheckout @id("space_collapse_mobile_checkout") strategy evidence-first target swiftui requires identity|runtime-proof produces view_checkout_mobile
+  admission mergeSafe @id("space_admission_merge_safe") kind semantic-merge status open requires hardConstraints|runtimeProof decision review failClosed
+}
+```
+
+The parser projects these blocks into `metadata.constraintSpaces`. Hard and soft constraints remain separate from preferences: hard constraints define validity, while preferences help choose among several valid shapes. `collapse` rows describe how a tool may choose a concrete projection, and `admission` rows describe what proof is required before a generated or merged shape should be accepted.
+
 ## Authored native source evidence
 
 `nativeSource` blocks can also carry source-bound merge evidence. This keeps parser/source-map/merge-candidate facts in `.frontier` text instead of requiring a raw JSON sidecar for the first authored program slice.

package/dist/constraint-space.js

@@ -0,0 +1,152 @@
+export function parseConstraintSpaceBlock(block) {
+  const name = nameFrom(block.header);
+  const space = {
+    id: idFrom(block.header, `constraint_space_${name}`),
+    name,
+    targets: [],
+    variables: [],
+    constraints: [],
+    preferences: [],
+    collapseStrategies: [],
+    admissions: [],
+    metadata: { name }
+  };
+  for (const rawLine of block.body.split('\n')) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#')) continue;
+    const target = /^target\s+([^\s,]+)/.exec(line)?.[1];
+    const subject = /^subject\s+([^\s,]+)/.exec(line)?.[1];
+    const scope = /^scope\s+([^\s,]+)/.exec(line)?.[1];
+    const record = /^(variable|var|constraint|hard|soft|preference|prefer|collapse|admission)\s+([A-Za-z_$][\w$-]*)(.*)$/.exec(line);
+    if (target) space.targets.push(target);
+    else if (subject) space.subjectId = subject;
+    else if (scope) space.scopeId = scope;
+    else if (record) addConstraintSpaceRecord(space, record[1], record[2], record[3]);
+  }
+  return cleanRecord({
+    ...space,
+    targets: unique(space.targets),
+    summary: {
+      variableCount: space.variables.length,
+      constraintCount: space.constraints.length,
+      preferenceCount: space.preferences.length,
+      collapseStrategyCount: space.collapseStrategies.length,
+      admissionCount: space.admissions.length
+    }
+  });
+}
+
+function addConstraintSpaceRecord(space, section, name, text) {
+  if (section === 'variable' || section === 'var') space.variables.push(parseVariable(name, text));
+  else if (section === 'constraint' || section === 'hard' || section === 'soft') space.constraints.push(parseConstraint(name, text, section));
+  else if (section === 'preference' || section === 'prefer') space.preferences.push(parsePreference(name, text));
+  else if (section === 'collapse') space.collapseStrategies.push(parseCollapseStrategy(name, text));
+  else if (section === 'admission') space.admissions.push(parseAdmission(name, text));
+}
+
+function parseVariable(name, text) {
+  return cleanRecord({
+    id: idFrom(text, `constraint_space_variable_${name}`),
+    name,
+    kind: readInlineWord('kind', text),
+    domain: readInlineList(text, 'domain', 'choices', 'values'),
+    default: readInlineWord('default', text),
+    subjectId: readInlineWord('subject', text) ?? readInlineWord('subjectId', text),
+    sourceId: readInlineWord('source', text) ?? readInlineWord('sourceId', text),
+    target: readInlineWord('target', text),
+    preserve: readInlineList(text, 'preserve', 'preserves'),
+    evidenceIds: readInlineList(text, 'evidence', 'evidenceIds'),
+    metadata: { name }
+  });
+}
+
+function parseConstraint(name, text, section) {
+  return cleanRecord({
+    id: idFrom(text, `constraint_space_constraint_${name}`),
+    name,
+    kind: readInlineWord('kind', text),
+    strength: readInlineWord('strength', text) ?? (section === 'hard' ? 'hard' : section === 'soft' ? 'soft' : undefined),
+    family: readInlineWord('family', text),
+    subjectId: readInlineWord('subject', text) ?? readInlineWord('subjectId', text),
+    variableIds: readInlineList(text, 'variable', 'variables', 'variableIds'),
+    target: readInlineWord('target', text),
+    predicate: readInlineQuoted('predicate', text) ?? readInlineWord('predicate', text),
+    requires: readInlineList(text, 'requires', 'required', 'require'),
+    evidenceIds: readInlineList(text, 'evidence', 'evidenceIds'),
+    proofObligationIds: readInlineList(text, 'proofObligation', 'proofObligations', 'proofObligationIds'),
+    conflictKeys: readInlineList(text, 'conflictKey', 'conflictKeys'),
+    failClosed: readInlineFlag('failClosed', text),
+    metadata: { name }
+  });
+}
+
+function parsePreference(name, text) {
+  return cleanRecord({
+    id: idFrom(text, `constraint_space_preference_${name}`),
+    name,
+    kind: readInlineWord('kind', text),
+    weight: readNumber(readInlineWord('weight', text)),
+    subjectId: readInlineWord('subject', text) ?? readInlineWord('subjectId', text),
+    variableIds: readInlineList(text, 'variable', 'variables', 'variableIds'),
+    target: readInlineWord('target', text),
+    prefer: readInlineList(text, 'prefer', 'prefers'),
+    reason: readInlineQuoted('reason', text) ?? readInlineWord('reason', text),
+    evidenceIds: readInlineList(text, 'evidence', 'evidenceIds'),
+    metadata: { name }
+  });
+}
+
+function parseCollapseStrategy(name, text) {
+  return cleanRecord({
+    id: idFrom(text, `constraint_space_collapse_${name}`),
+    name,
+    strategy: readInlineWord('strategy', text) ?? readInlineWord('kind', text),
+    target: readInlineWord('target', text),
+    variableIds: readInlineList(text, 'variable', 'variables', 'variableIds'),
+    requires: readInlineList(text, 'requires', 'required', 'require'),
+    produces: readInlineList(text, 'produces', 'produce', 'outputs', 'output'),
+    evidenceIds: readInlineList(text, 'evidence', 'evidenceIds'),
+    admissionIds: readInlineList(text, 'admission', 'admissions', 'admissionIds'),
+    status: readInlineWord('status', text),
+    metadata: { name }
+  });
+}
+
+function parseAdmission(name, text) {
+  return cleanRecord({
+    id: idFrom(text, `constraint_space_admission_${name}`),
+    name,
+    kind: readInlineWord('kind', text),
+    status: readInlineWord('status', text),
+    subjectId: readInlineWord('subject', text) ?? readInlineWord('subjectId', text),
+    target: readInlineWord('target', text),
+    requires: readInlineList(text, 'requires', 'required', 'require'),
+    evidenceIds: readInlineList(text, 'evidence', 'evidenceIds'),
+    decision: readInlineWord('decision', text),
+    reason: readInlineQuoted('reason', text) ?? readInlineWord('reason', text),
+    failClosed: readInlineFlag('failClosed', text),
+    metadata: { name }
+  });
+}
+
+function idFrom(text, fallback) { return /@id\(\s*["']([^"']+)["']\s*\)/.exec(text)?.[1] ?? fallback; }
+function nameFrom(header) { return /^([A-Za-z_$][\w$]*)/.exec(header)?.[1] ?? 'ConstraintSpace'; }
+function readInlineWord(label, text) { return new RegExp('(?:^|\\s)' + label + '\\s+([^\\s,]+)').exec(text)?.[1]?.trim(); }
+function readInlineQuoted(label, text) { return new RegExp("(?:^|\\s)" + label + "\\s+[\"']([^\"']+)[\"']").exec(text)?.[1]?.trim(); }
+function readInlineFlag(label, text) { return new RegExp('(?:^|\\s)' + label + '(?:\\s|$)').test(text) || undefined; }
+function readInlineList(text, ...labels) {
+  for (const label of labels) {
+    const value = new RegExp('(?:^|\\s)' + label + '\\s+([^\\s]+)').exec(text)?.[1]?.trim();
+    if (value) return value.split(/[|,]/).map((item) => item.trim()).filter(Boolean);
+  }
+  return undefined;
+}
+function readNumber(value) {
+  if (value === undefined) return undefined;
+  const number = Number(value);
+  return Number.isFinite(number) ? number : undefined;
+}
+function cleanRecord(record) {
+  return Object.fromEntries(Object.entries(record).filter(([, value]) => value !== undefined && (!Array.isArray(value) || value.length > 0)));
+}
+function unique(values) { return [...new Set(values.filter(Boolean))]; }

package/dist/index.js

@@ -1,4 +1,5 @@
 import { actionNode, capabilityNode, createDocument, effectNode, entityNode, externNode, latticeNode, migrationNode, stateNode, targetNode, typeNode } from '@shapeshift-labs/frontier-lang-kernel';
+import { parseConstraintSpaceBlock } from './constraint-space.js';
 import { parseConversionBlock } from './conversion.js';
 import { createParsedMetadata } from './metadata.js';
 import { parseSemanticOperationsBlock } from './operations.js';
@@ -13,6 +14,7 @@ export function parseFrontierSource(source, options = {}) {
   const paradigmBlocks = [];
   const operationBlocks = [];
   const conversionBlocks = [];
+  const constraintSpaceBlocks = [];
   const nativeSourceBlocks = [];
   const documentId = options.id ?? readId(source) ?? 'mod_frontier';
   const documentName = options.name ?? readName(source) ?? 'FrontierModule';
@@ -37,8 +39,9 @@ export function parseFrontierSource(source, options = {}) {
     if (block.kind === 'paradigm' || block.kind === 'paradigmSemantics') paradigmBlocks.push(parseParadigmBlock(block));
     if (block.kind === 'operations' || block.kind === 'semanticOperations') operationBlocks.push(parseSemanticOperationsBlock(block));
     if (block.kind === 'conversion' || block.kind === 'universalConversionPlan') conversionBlocks.push(parseConversionBlock(block));
+    if (block.kind === 'constraintSpace' || block.kind === 'possibilitySpace') constraintSpaceBlocks.push(parseConstraintSpaceBlock(block));
   }
-  const metadata = createParsedMetadata({ proofBlocks, paradigmBlocks, operationBlocks, conversionBlocks, nativeSourceBlocks });
+  const metadata = createParsedMetadata({ proofBlocks, paradigmBlocks, operationBlocks, conversionBlocks, constraintSpaceBlocks, nativeSourceBlocks });
   return createDocument({ id: documentId, name: documentName, nodes, ...(metadata ? { metadata } : {}) });
 }
 
@@ -48,7 +51,7 @@ function readName(source) { return /module\s+([A-Za-z_$][\w$]*)/.exec(source)?.[
 function readId(source) { return /module\s+[A-Za-z_$][\w$]*\s+@id\(\s*["']([^"']+)["']\s*\)/.exec(source)?.[1]; }
 function readBlocks(source) {
   const blocks = [];
-  const header = /\b(entity|state|action|view|migration|capability|effect|type|extern|lattice|nativeSource|target|proof|paradigm|paradigmSemantics|operations|semanticOperations|conversion|universalConversionPlan)\s+([^{}]+)\{/g;
+  const header = /\b(entity|state|action|view|migration|capability|effect|type|extern|lattice|nativeSource|target|proof|paradigm|paradigmSemantics|operations|semanticOperations|conversion|universalConversionPlan|constraintSpace|possibilitySpace)\s+([^{}]+)\{/g;
   let match;
   while ((match = header.exec(source))) {
     let depth = 1; let index = header.lastIndex;

package/dist/metadata.js

@@ -21,12 +21,13 @@ const PARADIGM_GROUPS = [
   'loweringRecords'
 ];
 
-export function createParsedMetadata({ proofBlocks = [], paradigmBlocks = [], operationBlocks = [], conversionBlocks = [], nativeSourceBlocks = [] } = {}) {
+export function createParsedMetadata({ proofBlocks = [], paradigmBlocks = [], operationBlocks = [], conversionBlocks = [], constraintSpaceBlocks = [], nativeSourceBlocks = [] } = {}) {
   const metadata = {};
   if (proofBlocks.length) metadata.proof = mergeProofBlocks(proofBlocks);
   if (paradigmBlocks.length) metadata.paradigmSemantics = mergeParadigmBlocks(paradigmBlocks);
   if (operationBlocks.length) metadata.semanticOperations = mergeOperationBlocks(operationBlocks);
   if (conversionBlocks.length) metadata.universalConversionPlan = mergeConversionBlocks(conversionBlocks);
+  if (constraintSpaceBlocks.length) metadata.constraintSpaces = mergeConstraintSpaceBlocks(constraintSpaceBlocks);
   if (nativeSourceBlocks.some((block) => block.sourceMaps.length || block.mergeCandidates.length || block.evidence.length)) {
     metadata.universalAst = mergeNativeSourceBlocks(nativeSourceBlocks);
   }
@@ -77,6 +78,28 @@ function mergeConversionBlocks(blocks) {
   return plan;
 }
 
+function mergeConstraintSpaceBlocks(blocks) {
+  return {
+    id: blocks.length === 1 ? blocks[0].id : 'constraintSpaces:source',
+    spaces: blocks,
+    targets: [...new Set(blocks.flatMap((block) => block.targets ?? []))],
+    variableIds: blocks.flatMap((block) => ids(block.variables)),
+    constraintIds: blocks.flatMap((block) => ids(block.constraints)),
+    preferenceIds: blocks.flatMap((block) => ids(block.preferences)),
+    collapseStrategyIds: blocks.flatMap((block) => ids(block.collapseStrategies)),
+    admissionIds: blocks.flatMap((block) => ids(block.admissions)),
+    summary: {
+      spaceCount: blocks.length,
+      variableCount: sum(blocks, 'variableCount'),
+      constraintCount: sum(blocks, 'constraintCount'),
+      preferenceCount: sum(blocks, 'preferenceCount'),
+      collapseStrategyCount: sum(blocks, 'collapseStrategyCount'),
+      admissionCount: sum(blocks, 'admissionCount')
+    },
+    metadata: { authoredConstraintSpaceBlockIds: blocks.map((block) => block.id) }
+  };
+}
+
 function mergeNativeSourceBlocks(blocks) {
   return {
     id: blocks.length === 1 ? `universalAst:${blocks[0].node.id}` : 'universalAst:source',
@@ -88,3 +111,11 @@ function mergeNativeSourceBlocks(blocks) {
     metadata: { authoredNativeSourceIds: blocks.map((block) => block.node.id) }
   };
 }
+
+function ids(records = []) {
+  return records.map((record) => record?.id).filter(Boolean);
+}
+
+function sum(blocks, key) {
+  return blocks.reduce((total, block) => total + (block.summary?.[key] ?? 0), 0);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shapeshift-labs/frontier-lang-parser",
-  "version": "0.3.17",
+  "version": "0.3.18",
   "description": "Parser for the first Frontier Lang .frontier syntax slice.",
   "type": "module",
   "main": "./dist/index.js",