@ldclabs/kip-lang 0.4.0 → 2.0.0

package/dist/exec-ast.d.ts

@@ -1,5 +1,5 @@
 /**
- * The *executable* KIP AST.
+ * The *executable* KIP 2.0 AST.
  *
  * This is a different tree from `ast.ts`, on purpose. `ast.ts` is a syntax
  * tree: it keeps ranges, comments, quoting style and raw number text, because
@@ -7,23 +7,46 @@
  * engine needs instead — every construct already collapsed to the one shape it
  * means, with the open-ended parts of the grammar closed:
  *
- *  - a concept matcher is one of four identified forms, not a bag of entries;
+ *  - a predicate is an atom or a path, not a nested alternation/quantifier tree;
  *  - a filter is a comparison, a logical node, a negation, or a call to one of
- *    seven functions, not a general expression tree;
- *  - a variable is a name and a dot path, not a chain of member accesses.
+ *    the registered functions, not a general expression tree;
+ *  - a variable is a name and a path of steps, not a chain of member accesses;
+ *  - `ASSERT` is gone: it has been desugared to the parts it is defined as.
  *
  * A consumer switching on these tags is total: there is no "some other
  * function name" case to defend against, because `lower` rejected it.
  *
- * The shape is the wire form of `anda_kip`'s Rust AST (serde's default
- * externally-tagged enum encoding), so an engine can consume either
- * interchangeably and a differential test can compare them field for field.
+ * The shape follows serde's default externally-tagged enum encoding, so a
+ * Rust engine can consume it directly and a differential test can compare the
+ * two field for field.
  */
-/** A JSON value, as carried by attribute and metadata blocks. */
-export type Json = null | boolean | number | string | Json[] | {
-    [key: string]: Json;
+/**
+ * A `data_value`: a value that may still contain unbound parameters.
+ *
+ * The grammar admits `parameter` at every depth of an array or object, so no
+ * assignment, option block or epistemic setting is plain JSON. A subtree with
+ * nothing left to bind collapses to `Value`; anything else keeps its shape so
+ * the runtime envelope can fill the holes without touching text.
+ */
+export type BoundValue = {
+    Value: KipValue;
+} | {
+    Param: string;
+} | {
+    Handle: string;
+} | {
+    Variable: DotPathVar;
+} | {
+    Array: BoundValue[];
+} | {
+    Object: [string, BoundValue][];
 };
-/** A KIP literal. Externally tagged; `Null` is a bare string. */
+/**
+ * A KIP literal. Externally tagged; `Null` is a bare string.
+ *
+ * Arrays and objects are not baseline Core Literals (Spec §9.2); they appear
+ * here only as the option/assignment payloads that the grammar admits.
+ */
 export type KipValue = 'Null' | {
     Bool: boolean;
 } | {
@@ -35,6 +58,32 @@ export type KipValue = 'Null' | {
 } | {
     Object: Record<string, KipValue>;
 };
+/**
+ * A value slot the grammar spells `parameter | literal`.
+ *
+ * KIP 2.0 parameters are structurally bound data, never string-spliced, so an
+ * unbound `:name` survives lowering as a `Param` for the runtime envelope to
+ * fill — it is not an error and never becomes text.
+ */
+export type Scalar = {
+    Literal: KipValue;
+} | {
+    Param: string;
+};
+/** A schema symbol: `string_literal | parameter`. */
+export type SymbolRef = {
+    Name: string;
+} | {
+    Param: string;
+};
+/** A mutation target: `variable | parameter | string_literal`. */
+export type ElementRef = {
+    Handle: string;
+} | {
+    Param: string;
+} | {
+    Id: string;
+};
 /** One parsed command. */
 export type Command = {
     Kql: KqlQuery;
@@ -43,21 +92,117 @@ export type Command = {
 } | {
     Meta: MetaCommand;
 };
+/** `?var` plus a resolved path, e.g. `?x.facets["MnemonicState"].salience`. */
+export interface DotPathVar {
+    var: string;
+    path: PathStep[];
+}
+/** A dot step names a field; an index step keys into a map-valued field. */
+export type PathStep = {
+    Field: string;
+} | {
+    Key: string;
+};
+/** `predicate_atom` — the exact predicate slot. */
+export type PredAtom = {
+    Variable: string;
+} | {
+    Literal: string;
+} | {
+    Param: string;
+};
+export interface HopRange {
+    min: number;
+    /** `null` means unbounded. */
+    max: number | null;
+}
+export interface PredPathAtom {
+    predicate: PredAtom;
+    hops: HopRange | null;
+}
+/**
+ * `Atom` is the plain predicate every language accepts. `Path` carries the
+ * KQL-only traversal forms — alternation and hop quantifiers — which never
+ * propagate belief and are rejected in KML and EXPORT selections.
+ */
+export type PredTerm = {
+    Atom: PredAtom;
+} | {
+    Path: PredPathAtom[];
+};
+/** One endpoint of a tuple. A term may itself be a tuple: KIP states things about statements. */
+export type Term = {
+    Variable: string;
+} | {
+    Param: string;
+} | {
+    Literal: KipValue;
+} | {
+    Match: ObjectMatcher;
+} | {
+    Proposition: PropositionMatcher;
+};
+/**
+ * `object_pattern` — an open, schema-validated field map.
+ *
+ * Unlike KIP 1.x, v2 does not close this to a fixed set of identity forms:
+ * which fields identify an element is Schema's decision, not the grammar's.
+ */
+export type ObjectMatcher = Record<string, MatchValue>;
+export type MatchValue = {
+    Variable: string;
+} | {
+    Param: string;
+} | {
+    Literal: KipValue;
+} | {
+    Array: MatchValue[];
+} | {
+    Match: ObjectMatcher;
+} | {
+    Proposition: PropositionMatcher;
+};
+export interface PropositionTriple {
+    subject: Term;
+    predicate: PredTerm;
+    object: Term;
+}
+/**
+ * The Proposition expression slot (Spec §43.2).
+ *
+ * `Tuple` addresses a Proposition by structure, `Id` by record identity. Both
+ * live in the same slot, which is why an id reference works everywhere a
+ * triple does — including as a {@link Term} endpoint. `Id` is match-only: it
+ * never resolves-or-creates, so `lower` rejects it in ENSURE PROPOSITION and
+ * in the ASSERT sugar that desugars through it.
+ */
+export type PropositionMatcher = {
+    Tuple: PropositionTriple;
+} | {
+    Id: Scalar;
+};
 export interface KqlQuery {
     find_clause: FindClause;
     where_clauses: WhereClause[];
+    /** Cognitive history basis — what the Brain contained/believed then. */
+    as_of: AsOf | null;
+    /** World-valid time — what was applicable then. An independent axis. */
+    for_time: Scalar | null;
+    epistemic: Record<string, BoundValue> | null;
     order_by: OrderByItem[] | null;
-    limit: number | null;
-    cursor: string | null;
+    limit: Scalar | null;
+    cursor: Scalar | null;
 }
+export type AsOf = {
+    Seq: Scalar;
+} | {
+    Tx: Scalar;
+} | {
+    Time: Scalar;
+};
 export interface FindClause {
     expressions: FindExpression[];
 }
-/** `?var` with an optional dot path, e.g. `?d.attributes.risk`. Names carry no `?`. */
-export interface DotPathVar {
-    var: string;
-    path: string[];
-}
 export type FindExpression = {
     Variable: DotPathVar;
 } | {
@@ -77,7 +222,7 @@ export type OrderDirection = 'Asc' | 'Desc';
 export type WhereClause = {
     Concept: {
         variable: string;
-        matcher: ConceptMatcher;
+        matcher: ObjectMatcher;
     };
 } | {
     Proposition: {
@@ -85,63 +230,64 @@ export type WhereClause = {
         matcher: PropositionMatcher;
     };
 } | {
-    Filter: {
-        expression: FilterExpression;
+    Assertion: {
+        variable: string;
+        matcher: ObjectMatcher;
     };
 } | {
-    Not: WhereClause[];
-} | {
-    Optional: WhereClause[];
+    Evidence: {
+        variable: string;
+        matcher: ObjectMatcher;
+    };
 } | {
-    Union: WhereClause[];
-};
-export type ConceptMatcher = {
-    ID: string;
+    Activity: {
+        variable: string;
+        matcher: ObjectMatcher;
+    };
 } | {
-    Type: string;
+    Structural: {
+        variable: string | null;
+        subject: Term;
+        field: SymbolRef;
+        object: Term;
+    };
 } | {
-    Name: string;
+    Belief: {
+        variable: string;
+        target: BeliefTarget;
+    };
 } | {
-    Object: {
-        type: string;
-        name: string;
+    BeliefSlot: {
+        variable: string;
+        subject: Term;
+        predicate: PredAtom;
     };
-};
-export type PropositionMatcher = {
-    ID: string;
 } | {
-    Object: {
-        subject: TargetTerm;
-        predicate: PredTerm;
-        object: TargetTerm;
+    Filter: {
+        expression: FilterExpression;
     };
+} | {
+    Not: WhereClause[];
+} | {
+    Optional: WhereClause[];
+} | {
+    Union: WhereClause[];
 };
 /**
- * One endpoint of a proposition pattern.
+ * What a BELIEF projects: an already-bound Proposition variable, a Proposition
+ * named by id, or a tuple stated inline.
  *
- * `Proposition` is the meta-statement case: an endpoint may itself be a
- * proposition, which is how KIP states things about statements. It nests
- * arbitrarily deep.
+ * `BELIEF (...)` is the Proposition expression slot, so the id form that names
+ * a Proposition in a pattern names it here too (Spec §43.2 / §46.1). The
+ * inline tuple always carries an exact predicate: projection never walks a
+ * raw path (Spec §45).
  */
-export type TargetTerm = {
-    Variable: string;
+export type BeliefTarget = {
+    Proposition: string;
 } | {
-    Concept: ConceptMatcher;
+    Id: Scalar;
 } | {
-    Proposition: PropositionMatcher;
-};
-export type PredTerm = {
-    Variable: string;
-} | {
-    Literal: string;
-} | {
-    Alternative: string[];
-} | {
-    MultiHop: {
-        predicate: string;
-        min: number;
-        max: number | null;
-    };
+    Tuple: PropositionTriple;
 };
 export type FilterExpression = {
     Comparison: {
@@ -168,73 +314,138 @@ export type FilterOperand = {
 } | {
     Literal: KipValue;
 } | {
-    List: KipValue[];
+    Param: string;
+} | {
+    List: FilterOperand[];
+} | {
+    Negate: FilterOperand;
 };
 export type ComparisonOperator = 'Equal' | 'NotEqual' | 'LessThan' | 'GreaterThan' | 'LessEqual' | 'GreaterEqual';
 export type LogicalOperator = 'And' | 'Or';
 export type FilterFunction = 'Contains' | 'StartsWith' | 'EndsWith' | 'Regex'
 /** `IN(?expr, [a, b])` — membership. A function, not a comparison operator. */
- | 'In' | 'IsNull' | 'IsNotNull';
-export type KmlStatement = {
-    Upsert: UpsertBlock[];
+ | 'In' | 'IsNull' | 'IsNotNull' | 'IsLiteral' | 'IsElement' | 'IsKind' | 'LiteralType';
+/**
+ * One atomic cognitive transition.
+ *
+ * A KML mutation becomes durable only via a Transaction, so a statement
+ * written on its own is still a one-clause transaction. `explicit_transaction`
+ * records which spelling the source used without changing that meaning.
+ */
+export interface KmlStatement {
+    explicit_transaction: boolean;
+    clauses: MutationClause[];
+}
+export type MutationClause = {
+    CreateConcept: ConceptCreate;
+} | {
+    UpsertConcept: ConceptUpsert;
+} | {
+    EnsureProposition: EnsureProposition;
+} | {
+    CreateEvidence: RecordCreate;
+} | {
+    CreateAssertion: RecordCreate;
+} | {
+    CreateActivity: RecordCreate;
 } | {
     Update: UpdateStatement;
 } | {
-    Merge: MergeStatement;
+    RetractAssertion: RetractAssertion;
 } | {
-    Delete: DeleteStatement;
-};
-export interface UpsertBlock {
-    items: UpsertItem[];
-    metadata: Record<string, Json> | null;
-}
-export type UpsertItem = {
-    Concept: ConceptBlock;
+    SupersedeAssertion: SupersedeAssertion;
 } | {
-    Proposition: PropositionBlock;
+    CorrectEvidence: CorrectEvidence;
+} | {
+    TransitionActivity: TransitionActivity;
+} | {
+    SetRetention: SetRetention;
+} | {
+    Archive: RemovalStatement;
+} | {
+    Tombstone: RemovalStatement;
+} | {
+    Purge: PurgeStatement;
+} | {
+    MergeConcept: MergeConcept;
 };
-export interface ConceptBlock {
-    handle: string | null;
-    concept: ConceptMatcher;
-    set_attributes: Record<string, Json> | null;
-    set_propositions: SetProposition[] | null;
-    metadata: Record<string, Json> | null;
-    /** `EXPECT VERSION <n>` — optimistic guard, omitted when not written. */
-    expect_version?: number;
+export interface ConceptCreate {
+    handle: string;
+    type: SymbolRef | null;
+    client_key: Scalar | null;
+    name: Scalar | null;
+    set_fields: Assignments | null;
+    set_attributes: Assignments | null;
+    set_facets: FacetAssignment[];
+    set_structural: StructuralEdge[] | null;
 }
-export interface SetProposition {
-    predicate: string;
-    object: TargetTerm;
-    metadata: Record<string, Json> | null;
+export interface ConceptUpsert {
+    handle: string;
+    match: ObjectMatcher | null;
+    expect_version: Scalar | null;
+    set_fields: Assignments | null;
+    set_attributes: Assignments | null;
+    set_facets: FacetAssignment[];
+    unset_attributes: string[] | null;
+    unset_facets: FacetUnset[];
+    set_structural: StructuralEdge[] | null;
+    unset_structural: StructuralRemoval[] | null;
 }
-export interface PropositionBlock {
+/** CREATE EVIDENCE / ASSERTION / ACTIVITY share one shape. */
+export interface RecordCreate {
+    handle: string;
+    client_key: Scalar | null;
+    set_fields: Assignments | null;
+    set_facets: FacetAssignment[];
+    set_structural: StructuralEdge[] | null;
+}
+export interface EnsureProposition {
     handle: string | null;
-    proposition: PropositionMatcher;
-    set_attributes: Record<string, Json> | null;
-    metadata: Record<string, Json> | null;
-    expect_version?: number;
+    subject: Term;
+    predicate: PredAtom;
+    object: Term;
+    expect_version: Scalar | null;
 }
-export interface UpdateStatement {
-    target: string;
-    set_attributes: [string, UpdateValue][] | null;
-    set_metadata: [string, UpdateValue][] | null;
-    where_clauses: WhereClause[];
-    limit: number | null;
+export interface FacetAssignment {
+    facet: SymbolRef;
+    values: Assignments;
+}
+export interface FacetUnset {
+    facet: SymbolRef;
+    fields: string[];
+}
+export interface StructuralEdge {
+    field: SymbolRef;
+    value: MutationValue;
+    /** Edge options; `index` is meaningful only on an ordered field. */
+    options: Record<string, BoundValue> | null;
 }
 /**
- * An UPDATE right-hand side: a literal, or arithmetic over the target's *own*
+ * `UNSET STRUCTURAL { (field, target) }` — one reference to remove.
+ *
+ * The SET STRUCTURAL edge without options: removal is per reference, ordered
+ * fields re-densify, cardinality is validated at commit (Spec §17.5).
+ */
+export interface StructuralRemoval {
+    field: SymbolRef;
+    value: MutationValue;
+}
+/** Assignment pairs, kept ordered so lowering stays deterministic. */
+export type Assignments = [string, MutationValue][];
+/**
+ * A KML right-hand side: a bound value, or arithmetic over the target's *own*
  * fields. References to any other variable are rejected during lowering, which
  * is what lets each matched element be updated from its own row without a join.
  */
-export type UpdateValue = {
-    Json: Json;
-} | {
+export type MutationValue = BoundValue | {
     Expr: UpdateExpr;
 };
 export type UpdateExpr = {
     Variable: DotPathVar;
 } | {
     Number: number;
+} | {
+    Param: string;
 } | {
     Function: {
         func: UpdateFunction;
@@ -242,73 +453,227 @@ export type UpdateExpr = {
     };
 };
 export type UpdateFunction = 'Add' | 'Mul' | 'Clamp' | 'Coalesce';
-export interface MergeStatement {
-    source: string;
-    target: string;
-    where_clauses: WhereClause[];
+export interface UpdateStatement {
+    target: ElementRef;
+    expect_version: Scalar | null;
+    actions: UpdateAction[];
+    /**
+     * `null` when the statement names its target directly and omits WHERE —
+     * the same shape as the removal family (Spec §58).
+     */
+    where_clauses: WhereClause[] | null;
+    limit: Scalar | null;
 }
-export type DeleteStatement = {
-    DeleteAttributes: {
-        attributes: string[];
-        target: string;
-        where_clauses: WhereClause[];
-    };
+export type UpdateAction = {
+    SetFields: Assignments;
 } | {
-    DeleteMetadata: {
-        keys: string[];
-        target: string;
-        where_clauses: WhereClause[];
-    };
+    SetAttributes: Assignments;
 } | {
-    DeletePropositions: {
-        target: string;
-        where_clauses: WhereClause[];
-    };
+    SetFacet: FacetAssignment;
 } | {
-    DeleteConcept: {
-        target: string;
-        where_clauses: WhereClause[];
-    };
+    UnsetAttributes: string[];
+} | {
+    UnsetFacet: FacetUnset;
+} | {
+    SetStructural: StructuralEdge[];
+} | {
+    UnsetStructural: StructuralRemoval[];
 };
+export interface RetractAssertion {
+    target: ElementRef;
+    where_clauses: WhereClause[] | null;
+    limit: Scalar | null;
+    expect_state: Scalar | null;
+}
+export interface SupersedeAssertion {
+    target: ElementRef;
+    by: ElementRef;
+    expect_state: Scalar | null;
+}
+export interface CorrectEvidence {
+    target: ElementRef;
+    by: ElementRef;
+    expect_state: Scalar | null;
+}
+export interface TransitionActivity {
+    target: ElementRef;
+    to: Scalar;
+    set_fields: Assignments | null;
+    set_structural: StructuralEdge[] | null;
+    expect_state: Scalar | null;
+}
+export interface SetRetention {
+    target: ElementRef;
+    values: Assignments;
+    where_clauses: WhereClause[] | null;
+    limit: Scalar | null;
+    expect_version: Scalar | null;
+}
+export interface RemovalStatement {
+    target: ElementRef;
+    where_clauses: WhereClause[] | null;
+    limit: Scalar | null;
+    expect_state: Scalar | null;
+}
+export interface PurgeStatement {
+    target: ElementRef;
+    where_clauses: WhereClause[] | null;
+    limit: Scalar | null;
+    reference_policy: Scalar | null;
+    /** Always the literal `PURGE`; the grammar freezes the spelling. */
+    confirm: string;
+}
+export interface MergeConcept {
+    source: ElementRef;
+    into: ElementRef;
+    where_clauses: WhereClause[] | null;
+    expect_version: Scalar | null;
+}
 export type MetaCommand = {
     Describe: DescribeTarget;
+} | {
+    List: ListCommand;
 } | {
     Search: SearchCommand;
 } | {
-    Export: ExportCommand;
+    Verify: {
+        target: VerifyTarget;
+        value: Scalar;
+    };
+} | {
+    Validate: ValidateCommand;
+} | {
+    Preview: PreviewCommand;
+} | {
+    History: HistoryCommand;
+} | {
+    Changes: ChangesCommand;
+} | {
+    Snapshot: {
+        as_of: AsOf | null;
+    };
+} | {
+    ExportCapsule: ExportCapsuleCommand;
 };
-export type DescribeTarget = 'Primer' | 'Domains' | {
-    ConceptTypes: {
-        limit: number | null;
-        cursor: string | null;
+export type DescribeTarget = {
+    Primer: {
+        mode: Scalar | null;
     };
+} | 'Protocol' | 'ExecutionContext' | 'Capabilities' | {
+    Space: {
+        value: Scalar | null;
+    };
+} | {
+    SchemaEnvironment: {
+        as_of: AsOf | null;
+    };
+} | {
+    Package: Scalar;
+} | {
+    Type: Scalar;
+} | {
+    Predicate: Scalar;
 } | {
-    ConceptType: string;
+    Facet: Scalar;
 } | {
-    PropositionTypes: {
-        limit: number | null;
-        cursor: string | null;
+    StructuralField: Scalar;
+} | {
+    Compatibility: {
+        from: Scalar;
+        to: Scalar;
+    };
+} | {
+    Error: Scalar;
+} | {
+    Transaction: Scalar;
+} | {
+    TransactionByIdempotencyKey: Scalar;
+} | {
+    Snapshot: {
+        as_of: AsOf | null;
     };
 } | {
-    PropositionType: string;
+    Capsule: Scalar;
+} | {
+    EpistemicPolicy: {
+        value: Scalar | null;
+    };
+} | 'ProjectionCapability' | {
+    Trust: {
+        value: Scalar | null;
+    };
+} | {
+    Access: {
+        with: Record<string, BoundValue> | null;
+    };
 };
+export interface ListCommand {
+    target: ListTarget;
+    /** `LIST SCHEMA PACKAGES STATUS ...` only. */
+    status: Scalar | null;
+    limit: Scalar | null;
+    cursor: Scalar | null;
+}
+export type ListTarget = 'Spaces' | 'SchemaPackages' | 'Types' | 'Predicates' | 'Facets' | 'StructuralFields' | 'EpistemicPolicies';
 export interface SearchCommand {
     target: SearchTarget;
-    term: string;
-    in_type: string | null;
-    /** Omitted when the command wrote no `MODE`. */
-    mode?: SearchMode;
-    /** Omitted when the command wrote no `THRESHOLD`. */
-    threshold?: number;
-    limit: number | null;
+    term: Scalar;
+    with_type: Scalar | null;
+    with_predicate: Scalar | null;
+    mode: Scalar | null;
+    threshold: Scalar | null;
+    /** Historical index basis, `AS OF SEQ`. */
+    as_of_seq: Scalar | null;
+    limit: Scalar | null;
+    cursor: Scalar | null;
 }
-export type SearchTarget = 'Concept' | 'Proposition';
-export type SearchMode = 'Keyword' | 'Semantic' | 'Hybrid';
-export interface ExportCommand {
-    target: string;
+export type SearchTarget = 'Concept' | 'Proposition' | 'Assertion' | 'Evidence' | 'Activity' | 'Cognition';
+export type VerifyTarget = 'Capsule' | 'SchemaPackage' | 'Receipt' | 'Blob' | 'Checkpoint';
+export interface ValidateCommand {
+    target: ValidateTarget;
+    value: Scalar;
+    options: Record<string, BoundValue> | null;
+}
+export type ValidateTarget = 'Kql' | 'Kml' | 'Capsule' | 'SchemaPackage' | 'ImportPlan';
+export type PreviewCommand = {
+    Kml: Scalar;
+} | {
+    ImportCapsule: {
+        capsule: Scalar;
+        into: Scalar;
+    };
+};
+export type HistoryCommand = {
+    Element: {
+        value: Scalar;
+        from_seq: Scalar | null;
+        to_seq: Scalar | null;
+        limit: Scalar | null;
+        cursor: Scalar | null;
+    };
+} | {
+    Space: {
+        from_seq: Scalar | null;
+        to_seq: Scalar | null;
+        limit: Scalar | null;
+        cursor: Scalar | null;
+    };
+};
+export type ChangesCommand = {
+    Since: {
+        cursor: Scalar;
+        limit: Scalar | null;
+    };
+} | {
+    AfterSeq: {
+        seq: Scalar;
+        limit: Scalar | null;
+    };
+};
+export interface ExportCapsuleCommand {
+    target: ElementRef;
     where_clauses: WhereClause[];
-    limit: number | null;
-    /** Omitted when the command wrote no `CURSOR`. */
-    cursor?: string;
+    options: Record<string, BoundValue> | null;
+    as_of: AsOf | null;
 }
 //# sourceMappingURL=exec-ast.d.ts.map