@ldclabs/kip-lang 2.0.2 → 2.2.0

package/src/lower.ts

@@ -32,14 +32,11 @@ import type {
   SetStructuralClause,
   UnsetStructuralClause,
   UnsetField,
-  RetractAssertionStatement,
-  SupersedeAssertionStatement,
-  CorrectEvidenceStatement,
-  TransitionActivityStatement,
+  ExpectVersionClause,
+  TransitionStatement,
   SetRetentionStatement,
-  ArchiveStatement,
-  TombstoneStatement,
   PurgeStatement,
+  PurgePayloadStatement,
   MergeConceptStatement,
   DescribeStatement,
   ListStatement,
@@ -49,7 +46,6 @@ import type {
   PreviewStatement,
   HistoryStatement,
   ChangesStatement,
-  SnapshotStatement,
   ExportCapsuleStatement,
   NumberLiteral
 } from './ast.js'
@@ -67,6 +63,9 @@ import type {
   DotPathVar,
   ElementRef,
   EnsureProposition,
+  ExpectVersion,
+  VersionPlane,
+  Transition,
   FacetAssignment,
   FacetUnset,
   FilterExpression,
@@ -245,14 +244,10 @@ export function lowerStatement(stmt: Statement): Command {
     case 'CreateAssertionStatement':
     case 'CreateActivityStatement':
     case 'UpdateStatement':
-    case 'RetractAssertionStatement':
-    case 'SupersedeAssertionStatement':
-    case 'CorrectEvidenceStatement':
-    case 'TransitionActivityStatement':
+    case 'TransitionStatement':
     case 'SetRetentionStatement':
-    case 'ArchiveStatement':
-    case 'TombstoneStatement':
     case 'PurgeStatement':
+    case 'PurgePayloadStatement':
     case 'MergeConceptStatement':
       const clauses = lowerMutationClause(stmt, 0)
       assertUniqueHandles(clauses, stmt.range)
@@ -292,15 +287,50 @@ function lowerFind(stmt: FindStatement): KqlQuery {
 }
 
 function lowerAsOf(clause: AsOfClause): AsOf {
-  const value = lowerScalar(clause.value)
-  switch (clause.basis) {
-    case 'SEQ':
-      return { Seq: value }
-    case 'TX':
-      return { Tx: value }
-    case 'TIME':
-      return { Time: value }
-  }
+  return { Seq: lowerScalar(clause.value) }
+}
+
+/**
+ * `{ expect_version_clause }` → at most one guard per plane. Two guards on one
+ * plane cannot both be meant, so the duplicate is rejected here rather than
+ * left for the engine to pick one.
+ */
+function lowerExpectVersions(clauses: ExpectVersionClause[]): ExpectVersion[] {
+  const seen = new Set<string>()
+  return clauses.map((clause) => {
+    let plane: VersionPlane | null = null
+    let key = 'element'
+    if (clause.plane) {
+      switch (clause.plane.kind) {
+        case 'ATTRIBUTES':
+          plane = 'Attributes'
+          key = 'attributes'
+          break
+        case 'STRUCTURAL':
+          plane = 'Structural'
+          key = 'structural'
+          break
+        case 'RETENTION':
+          plane = 'Retention'
+          key = 'retention'
+          break
+        case 'FACET': {
+          const facet = lowerSymbol(clause.plane.facet)
+          plane = { Facet: facet }
+          key = 'facet:' + ('Name' in facet ? facet.Name : ':' + facet.Param)
+          break
+        }
+      }
+    }
+    if (seen.has(key)) {
+      throw invalidSyntax(
+        `duplicate EXPECT VERSION guard on the same ${key === 'element' ? 'element' : 'plane'}`,
+        clause.range
+      )
+    }
+    seen.add(key)
+    return { version: lowerScalar(clause.value), plane }
+  })
 }
 
 function lowerFindExpression(expr: Expression): FindExpression {
@@ -862,45 +892,8 @@ function lowerMutationClause(
       return [{ CreateActivity: lowerRecordCreate(stmt) }]
     case 'UpdateStatement':
       return [{ Update: lowerUpdate(stmt) }]
-    case 'RetractAssertionStatement':
-      return [
-        {
-          RetractAssertion: {
-            target: lowerElementRef(stmt.target),
-            where_clauses: stmt.where ? lowerWhere(stmt.where) : null,
-            limit: stmt.limit ? lowerScalar(stmt.limit.value) : null,
-            expect_state: stmt.expectState
-              ? lowerScalar(stmt.expectState.value)
-              : null
-          }
-        }
-      ]
-    case 'SupersedeAssertionStatement':
-      return [
-        {
-          SupersedeAssertion: {
-            target: lowerElementRef(stmt.target),
-            by: lowerElementRef(stmt.by),
-            expect_state: stmt.expectState
-              ? lowerScalar(stmt.expectState.value)
-              : null
-          }
-        }
-      ]
-    case 'CorrectEvidenceStatement':
-      return [
-        {
-          CorrectEvidence: {
-            target: lowerElementRef(stmt.target),
-            by: lowerElementRef(stmt.by),
-            expect_state: stmt.expectState
-              ? lowerScalar(stmt.expectState.value)
-              : null
-          }
-        }
-      ]
-    case 'TransitionActivityStatement':
-      return [{ TransitionActivity: lowerTransition(stmt) }]
+    case 'TransitionStatement':
+      return [{ Transition: lowerTransition(stmt) }]
     case 'SetRetentionStatement':
       return [
         {
@@ -909,18 +902,14 @@ function lowerMutationClause(
             values: lowerAssignments(stmt.assignments, null),
             where_clauses: stmt.where ? lowerWhere(stmt.where) : null,
             limit: stmt.limit ? lowerScalar(stmt.limit.value) : null,
-            expect_version: stmt.expectVersion
-              ? lowerScalar(stmt.expectVersion.value)
-              : null
+            expect_versions: lowerExpectVersions(stmt.expectVersions)
           }
         }
       ]
-    case 'ArchiveStatement':
-      return [{ Archive: lowerRemoval(stmt) }]
-    case 'TombstoneStatement':
-      return [{ Tombstone: lowerRemoval(stmt) }]
     case 'PurgeStatement':
       return [{ Purge: lowerPurge(stmt) }]
+    case 'PurgePayloadStatement':
+      return [{ PurgePayload: lowerPurgePayload(stmt) }]
     case 'MergeConceptStatement':
       return [
         {
@@ -928,9 +917,7 @@ function lowerMutationClause(
             source: lowerElementRef(stmt.source),
             into: lowerElementRef(stmt.into),
             where_clauses: stmt.where ? lowerWhere(stmt.where) : null,
-            expect_version: stmt.expectVersion
-              ? lowerScalar(stmt.expectVersion.value)
-              : null
+            expect_versions: lowerExpectVersions(stmt.expectVersions)
           }
         }
       ]
@@ -999,9 +986,7 @@ function lowerUpsertConcept(stmt: UpsertConceptStatement): ConceptUpsert {
   return {
     handle: varName(stmt.handle.name, stmt.handle.range),
     match,
-    expect_version: stmt.expectVersion
-      ? lowerScalar(stmt.expectVersion.value)
-      : null,
+    expect_versions: lowerExpectVersions(stmt.expectVersions),
     set_fields: stmt.setFields
       ? lowerAssignments(stmt.setFields.assignments, null)
       : null,
@@ -1032,9 +1017,7 @@ function lowerEnsureProposition(
   return {
     handle: stmt.handle ? varName(stmt.handle.name, stmt.handle.range) : null,
     ...triple,
-    expect_version: stmt.expectVersion
-      ? lowerScalar(stmt.expectVersion.value)
-      : null
+    expect_versions: lowerExpectVersions(stmt.expectVersions)
   }
 }
 
@@ -1060,7 +1043,7 @@ function lowerRecordCreate(
 
 /**
  * Desugars `ASSERT` into exactly what the Spec defines it as (§55.1):
- * `ENSURE PROPOSITION` + `CREATE ASSERTION`, plus `SUPERSEDE` when written.
+ * `ENSURE PROPOSITION` + `CREATE ASSERTION`, plus `TRANSITION ... TO "superseded"` when `SUPERSEDING` is written.
  *
  * Nothing else is fabricated. The sugar exists because recording an
  * attributed claim is the hot path, not because it means anything new.
@@ -1131,7 +1114,7 @@ function lowerAssertSugar(
       EnsureProposition: {
         handle: propositionHandle,
         ...triple,
-        expect_version: null
+        expect_versions: []
       }
     }
   ]
@@ -1189,10 +1172,15 @@ function lowerAssertSugar(
 
   if (stmt.superseding) {
     clauses.push({
-      SupersedeAssertion: {
+      Transition: {
         target: lowerElementRef(stmt.superseding),
+        to: { Literal: { String: 'superseded' } },
         by: { Handle: assertionHandle },
-        expect_state: null
+        set_fields: null,
+        set_structural: null,
+        where_clauses: null,
+        limit: null,
+        expect_versions: []
       }
     })
   }
@@ -1200,7 +1188,33 @@ function lowerAssertSugar(
   return clauses
 }
 
-function lowerTransition(stmt: TransitionActivityStatement) {
+/** Moves that name the replacing element with `BY` (Spec §52.5). */
+const TRANSITION_WITH_BY = new Set(['superseded', 'corrected'])
+/** Activity status moves: the only ones that may finalize fields or topology. */
+const TRANSITION_ACTIVITY_STATES = new Set(['running', 'completed', 'failed', 'cancelled'])
+
+function lowerTransition(stmt: TransitionStatement): Transition {
+  // Spec §52.5: BY exactly for superseded / corrected, SET clauses only on
+  // Activity states. These are syntax errors, so they belong to the
+  // executability contract, not only to the editor diagnostics.
+  if (stmt.to.kind === 'StringLiteral') {
+    const to = stmt.to.parsed
+    if (TRANSITION_WITH_BY.has(to) && !stmt.by) {
+      throw invalidSyntax(
+        `TRANSITION TO "${to}" names the replacing element with BY`,
+        stmt.to.range
+      )
+    }
+    if (!TRANSITION_WITH_BY.has(to) && stmt.by) {
+      throw invalidSyntax(`TRANSITION TO "${to}" takes no BY`, stmt.by.range)
+    }
+    if (stmt.finalize.length > 0 && !TRANSITION_ACTIVITY_STATES.has(to)) {
+      throw invalidSyntax(
+        `TRANSITION TO "${to}" cannot finalize fields or topology; only a pending Activity does`,
+        stmt.finalize[0].range
+      )
+    }
+  }
   let setFields: Assignments | null = null
   let setStructural: StructuralEdge[] | null = null
   for (const clause of stmt.finalize) {
@@ -1219,18 +1233,12 @@ function lowerTransition(stmt: TransitionActivityStatement) {
   return {
     target: lowerElementRef(stmt.target),
     to: lowerScalar(stmt.to),
+    by: stmt.by ? lowerElementRef(stmt.by) : null,
     set_fields: setFields,
     set_structural: setStructural,
-    expect_state: stmt.expectState ? lowerScalar(stmt.expectState.value) : null
-  }
-}
-
-function lowerRemoval(stmt: ArchiveStatement | TombstoneStatement) {
-  return {
-    target: lowerElementRef(stmt.target),
     where_clauses: stmt.where ? lowerWhere(stmt.where) : null,
     limit: stmt.limit ? lowerScalar(stmt.limit.value) : null,
-    expect_state: stmt.expectState ? lowerScalar(stmt.expectState.value) : null
+    expect_versions: lowerExpectVersions(stmt.expectVersions)
   }
 }
 
@@ -1245,6 +1253,7 @@ function lowerPurge(stmt: PurgeStatement) {
     target: lowerElementRef(stmt.target),
     where_clauses: stmt.where ? lowerWhere(stmt.where) : null,
     limit: stmt.limit ? lowerScalar(stmt.limit.value) : null,
+    expect_versions: lowerExpectVersions(stmt.expectVersions),
     reference_policy: stmt.referencePolicy
       ? lowerScalar(stmt.referencePolicy)
       : null,
@@ -1252,6 +1261,22 @@ function lowerPurge(stmt: PurgeStatement) {
   }
 }
 
+function lowerPurgePayload(stmt: PurgePayloadStatement) {
+  if (stmt.confirm.parsed !== 'PURGE') {
+    throw invalidSyntax(
+      'PURGE PAYLOAD must be confirmed with the exact literal "PURGE"',
+      stmt.confirm.range
+    )
+  }
+  return {
+    target: lowerElementRef(stmt.target),
+    where_clauses: stmt.where ? lowerWhere(stmt.where) : null,
+    limit: stmt.limit ? lowerScalar(stmt.limit.value) : null,
+    expect_versions: lowerExpectVersions(stmt.expectVersions),
+    confirm: 'PURGE'
+  }
+}
+
 // ---------------------------------------------------------------------------
 // UPDATE
 // ---------------------------------------------------------------------------
@@ -1275,12 +1300,10 @@ function lowerUpdate(stmt: CstUpdateStatement) {
 
   return {
     target,
-    expect_version: stmt.expectVersion
-      ? lowerScalar(stmt.expectVersion.value)
-      : null,
     actions,
     where_clauses: stmt.where ? lowerWhere(stmt.where) : null,
-    limit: stmt.limit ? lowerScalar(stmt.limit.value) : null
+    limit: stmt.limit ? lowerScalar(stmt.limit.value) : null,
+    expect_versions: lowerExpectVersions(stmt.expectVersions)
   }
 }
 
@@ -1377,7 +1400,7 @@ function lowerUpdateAction(
  * Structural mutation reaches mutable Concept topology only (Spec §17.5).
  * Record kinds keep their topology: an Assertion's citations and an
  * Evidence's lineage are immutable payload, a Proposition has no structural
- * fields, and a pending Activity finalizes through TRANSITION ACTIVITY.
+ * fields, and a pending Activity finalizes through TRANSITION.
  */
 function guardStructuralMutation(
   verb: string,
@@ -1392,7 +1415,7 @@ function guardStructuralMutation(
       )
     case 'evidence':
       throw invalidSyntax(
-        `${verb} cannot change Evidence topology: correct it with CORRECT EVIDENCE :old BY :new`,
+        `${verb} cannot change Evidence topology: correct it with TRANSITION :old TO "corrected" BY :new`,
         range
       )
     case 'proposition':
@@ -1402,7 +1425,7 @@ function guardStructuralMutation(
       )
     case 'activity':
       throw invalidSyntax(
-        `${verb} cannot change Activity topology: finalize a pending Activity with TRANSITION ACTIVITY ... SET STRUCTURAL; a terminal Activity is immutable`,
+        `${verb} cannot change Activity topology: finalize a pending Activity with TRANSITION ... TO "completed" SET STRUCTURAL; a terminal Activity is immutable`,
         range
       )
     default:
@@ -1436,7 +1459,7 @@ function guardImmutableField(
   }
   if (kind === 'evidence' && EVIDENCE_IMMUTABLE.has(field)) {
     throw invalidSyntax(
-      `${field} is immutable Evidence payload: correct it with CORRECT EVIDENCE :old BY :new`,
+      `${field} is immutable Evidence payload: correct it with TRANSITION :old TO "corrected" BY :new`,
       range
     )
   }
@@ -1734,8 +1757,6 @@ function lowerMeta(stmt: Statement): MetaCommand {
                 }
               }
       }
-    case 'SnapshotStatement':
-      return { Snapshot: { as_of: stmt.asOf ? lowerAsOf(stmt.asOf) : null } }
     case 'ExportCapsuleStatement':
       return { ExportCapsule: lowerExport(stmt) }
     default:
@@ -1769,7 +1790,8 @@ const LIST_TARGETS: Record<ListStatement['target'], ListTarget> = {
   PREDICATES: 'Predicates',
   FACETS: 'Facets',
   STRUCTURAL_FIELDS: 'StructuralFields',
-  EPISTEMIC_POLICIES: 'EpistemicPolicies'
+  EPISTEMIC_POLICIES: 'EpistemicPolicies',
+  DEPENDENTS: 'Dependents'
 }
 
 const SEARCH_TARGETS: Record<SearchStatement['searchKind'], SearchTarget> = {
@@ -1797,8 +1819,6 @@ function lowerDescribe(stmt: DescribeStatement): DescribeTarget {
       return { Primer: { mode: stmt.mode ? lowerScalar(stmt.mode) : null } }
     case 'PROTOCOL':
       return 'Protocol'
-    case 'EXECUTION_CONTEXT':
-      return 'ExecutionContext'
     case 'CAPABILITIES':
       return 'Capabilities'
     case 'SPACE':
@@ -1834,15 +1854,18 @@ function lowerDescribe(stmt: DescribeStatement): DescribeTarget {
     case 'TRANSACTION_BY_IDEMPOTENCY_KEY':
       return { TransactionByIdempotencyKey: value() }
     case 'SNAPSHOT':
-      return { Snapshot: { as_of: stmt.asOf ? lowerAsOf(stmt.asOf) : null } }
+      return {
+        Snapshot: {
+          as_of: stmt.asOf ? lowerAsOf(stmt.asOf) : null,
+          at_time: stmt.atTime ? lowerScalar(stmt.atTime) : null
+        }
+      }
     case 'CAPSULE':
       return { Capsule: value() }
     case 'EPISTEMIC_POLICY':
       return {
         EpistemicPolicy: { value: stmt.value ? lowerScalar(stmt.value) : null }
       }
-    case 'PROJECTION_CAPABILITY':
-      return 'ProjectionCapability'
     case 'TRUST':
       return { Trust: { value: stmt.value ? lowerScalar(stmt.value) : null } }
     case 'ACCESS':
@@ -1853,9 +1876,14 @@ function lowerDescribe(stmt: DescribeStatement): DescribeTarget {
 }
 
 function lowerList(stmt: ListStatement) {
+  if (stmt.target === 'DEPENDENTS' && !stmt.element) {
+    throw invalidSyntax('LIST DEPENDENTS requires an element operand', stmt.range)
+  }
   return {
     target: LIST_TARGETS[stmt.target],
     status: stmt.status ? lowerScalar(stmt.status) : null,
+    element: stmt.element ? lowerScalar(stmt.element) : null,
+    depth: stmt.depth ? lowerScalar(stmt.depth) : null,
     limit: stmt.limit ? lowerScalar(stmt.limit.value) : null,
     cursor: stmt.cursor ? lowerScalar(stmt.cursor.value) : null
   }