@kanonak-protocol/sdk 3.11.0 → 3.12.0

package/dist/transformations/v3/CompiledTransformationV3.d.ts

@@ -0,0 +1,370 @@
+/**
+ * Typed, parsed-once representation of a transformations@3.0.0
+ * Transformation. Produced by `TransformationLoaderV3` from a
+ * `SubjectKanonak` whose RDF type is either `InstanceTransformation`
+ * or `SetTransformation`; consumed by `TransformationRunnerV3` and
+ * `ExpressionEngineV3`.
+ *
+ * The full Expression type union is declared here even though slice 1
+ * only implements a subset — declaring it upfront means later slices
+ * add behavior (loader cases, engine cases) rather than type members.
+ *
+ * V3 SHAPE NOTES (vs V2):
+ *   - Top level is a discriminated union over `kind: 'instance' | 'set'`,
+ *     mirroring the InstanceTransformation/SetTransformation split.
+ *   - InputPattern carries `sortBy` (ordered list of SortKeys); the V2
+ *     pattern had no sort.
+ *   - SetTransformation may carry `partitionBy` for fan-out.
+ *   - Expression nodes are tagged by their `kind` string here (the
+ *     compiled form), but in the YAML they're dispatched by RDF type
+ *     (real OWL hierarchy, not a discriminator instance).
+ */
+import type { EntityUri } from '../../uri-helpers/UriHelpers.js';
+export type CompiledTransformationV3 = CompiledInstanceTransformationV3 | CompiledSetTransformationV3;
+export interface CompiledTransformationV3Base {
+    /** Local name of the transformation entity, for diagnostics. */
+    name: string;
+    inputPattern: CompiledInputPatternV3;
+    rule: CompiledExpressionV3;
+    artifactName: CompiledExpressionV3;
+    /**
+     * The set of OutputFormat URIs this transformation supports, keyed
+     * by the OutputFormat's local name. The runner rejects requests to
+     * render in a format not in this set.
+     */
+    outputs: Set<string>;
+    /** Per-output-format overrides keyed by the OutputFormat's local name. */
+    overrides: Map<string, CompiledFormatOverrideV3>;
+}
+export interface CompiledInstanceTransformationV3 extends CompiledTransformationV3Base {
+    kind: 'instance';
+}
+export interface CompiledSetTransformationV3 extends CompiledTransformationV3Base {
+    kind: 'set';
+    /**
+     * When set, the runner partitions the matched input set on this
+     * property and emits one Artifact per partition; `key` and `inputs`
+     * are bound for each evaluation. When undefined, the runner runs
+     * `rule` and `artifactName` once with `inputs` bound to the whole
+     * matched set, emitting a single Artifact.
+     */
+    partitionBy?: EntityUri | undefined;
+}
+export interface CompiledInputPatternV3 {
+    /** The class URI whose instances are eligible. */
+    matchesClass: EntityUri;
+    /** Property URIs that must each resolve to non-empty on each instance. */
+    requires: EntityUri[];
+    /**
+     * Ordered list of sort criteria (primary first, ties broken by
+     * subsequent keys). Empty for transformations that don't need order.
+     */
+    sortBy: CompiledSortKeyV3[];
+}
+export interface CompiledSortKeyV3 {
+    byProperty: EntityUri;
+    order: 'ascending' | 'descending';
+}
+export interface CompiledFormatOverrideV3 {
+    metadataKeys?: string[] | undefined;
+    metadataRenames: Map<string, string>;
+    trailingNewline?: boolean | undefined;
+    /** When true, backends suppress their default chrome (HTML's
+     *  doctype + style + metadata <dl>; analogous in other backends). */
+    omitWrapper?: boolean | undefined;
+}
+export type CompiledExpressionV3 = CompiledStringLiteralV3 | CompiledIntegerLiteralV3 | CompiledDecimalLiteralV3 | CompiledBooleanLiteralV3 | CompiledVarRefV3 | CompiledPropertyReadV3 | CompiledTraverseV3 | CompiledBuildAstNodeV3 | CompiledWhenV3 | CompiledConcatV3 | CompiledFallbackV3 | CompiledUriNameV3 | CompiledUriPublisherV3 | CompiledUriPackageV3 | CompiledUriVersionV3 | CompiledSubjectUriV3 | CompiledUriLiteralV3 | CompiledDisplayLabelV3 | CompiledResolveRefV3 | CompiledNormalizeV3 | CompiledIsSetV3 | CompiledCallFragmentV3 | CompiledJoinV3 | CompiledCountV3 | CompiledSumV3 | CompiledMinV3 | CompiledMaxV3 | CompiledAverageV3 | CompiledForEachV3 | CompiledListMapV3 | CompiledFilterV3 | CompiledPartitionByV3 | CompiledDistinctByV3 | CompiledAllStatementsV3 | CompiledStatementPredicateV3 | CompiledStatementValueV3 | CompiledDateFormatV3 | CompiledAddV3 | CompiledSubtractV3 | CompiledMultiplyV3 | CompiledDivideV3 | CompiledReverseV3 | CompiledWindowedMapV3 | CompiledPairwiseMapV3 | CompiledScanV3 | CompiledListItemAtV3 | CompiledEqualsV3 | CompiledGreaterThanV3 | CompiledLessThanV3 | CompiledGreaterThanOrEqualV3 | CompiledLessThanOrEqualV3 | CompiledNotV3 | CompiledAndV3 | CompiledOrV3 | CompiledContainsV3 | CompiledAbsV3 | CompiledNegateV3 | CompiledIsReferenceV3 | CompiledIsEmbeddedV3 | CompiledIsListV3 | CompiledStatementObjectV3;
+export interface CompiledStringLiteralV3 {
+    kind: 'string-literal';
+    value: string;
+}
+export interface CompiledIntegerLiteralV3 {
+    kind: 'integer-literal';
+    value: number;
+}
+export interface CompiledDecimalLiteralV3 {
+    kind: 'decimal-literal';
+    value: number;
+}
+export interface CompiledBooleanLiteralV3 {
+    kind: 'boolean-literal';
+    value: boolean;
+}
+export interface CompiledVarRefV3 {
+    kind: 'var-ref';
+    varName: string;
+}
+export interface CompiledPropertyReadV3 {
+    kind: 'property-read';
+    source: CompiledExpressionV3;
+    readProp: EntityUri;
+}
+export interface CompiledTraverseV3 {
+    kind: 'traverse';
+    source: CompiledExpressionV3;
+    through: EntityUri;
+    step: CompiledExpressionV3;
+}
+export interface CompiledBuildAstNodeV3 {
+    kind: 'build-ast-node';
+    astClass: EntityUri;
+    set: CompiledFieldBindingV3[];
+}
+export interface CompiledFieldBindingV3 {
+    field: EntityUri;
+    value: CompiledExpressionV3;
+}
+export interface CompiledWhenV3 {
+    kind: 'when';
+    condition: CompiledExpressionV3;
+    thenBuild: CompiledExpressionV3;
+    elseBuild?: CompiledExpressionV3 | undefined;
+}
+export interface CompiledConcatV3 {
+    kind: 'concat';
+    parts: CompiledExpressionV3[];
+}
+export interface CompiledFallbackV3 {
+    kind: 'fallback';
+    primary: CompiledExpressionV3;
+    alternate: CompiledExpressionV3;
+}
+export interface CompiledUriNameV3 {
+    kind: 'uri-name';
+    source: CompiledExpressionV3;
+}
+export interface CompiledUriPublisherV3 {
+    kind: 'uri-publisher';
+    source: CompiledExpressionV3;
+}
+export interface CompiledUriPackageV3 {
+    kind: 'uri-package';
+    source: CompiledExpressionV3;
+}
+export interface CompiledUriVersionV3 {
+    kind: 'uri-version';
+    source: CompiledExpressionV3;
+}
+export interface CompiledSubjectUriV3 {
+    kind: 'subject-uri';
+    source: CompiledExpressionV3;
+}
+export interface CompiledUriLiteralV3 {
+    kind: 'uri-literal';
+    refTo: EntityUri;
+}
+export interface CompiledDisplayLabelV3 {
+    kind: 'display-label';
+    labelTarget: EntityUri;
+    labelSource: EntityUri;
+}
+export interface CompiledResolveRefV3 {
+    kind: 'resolve-ref';
+    source: CompiledExpressionV3;
+}
+export interface CompiledAllStatementsV3 {
+    kind: 'all-statements';
+    source: CompiledExpressionV3;
+}
+export interface CompiledStatementPredicateV3 {
+    kind: 'statement-predicate';
+    source: CompiledExpressionV3;
+}
+export interface CompiledStatementValueV3 {
+    kind: 'statement-value';
+    source: CompiledExpressionV3;
+}
+/** Named output formats supported by the engine. */
+export type DateFormatKindV3 = 'iso-date' | 'iso-datetime' | 'short-date' | 'long-date' | 'year' | 'month-year';
+export interface CompiledDateFormatV3 {
+    kind: 'date-format';
+    source: CompiledExpressionV3;
+    format: DateFormatKindV3;
+}
+export interface CompiledAddV3 {
+    kind: 'add';
+    left: CompiledExpressionV3;
+    right: CompiledExpressionV3;
+}
+export interface CompiledSubtractV3 {
+    kind: 'subtract';
+    left: CompiledExpressionV3;
+    right: CompiledExpressionV3;
+}
+export interface CompiledMultiplyV3 {
+    kind: 'multiply';
+    left: CompiledExpressionV3;
+    right: CompiledExpressionV3;
+}
+export interface CompiledDivideV3 {
+    kind: 'divide';
+    left: CompiledExpressionV3;
+    right: CompiledExpressionV3;
+}
+export interface CompiledReverseV3 {
+    kind: 'reverse';
+    source: CompiledExpressionV3;
+}
+export interface CompiledWindowedMapV3 {
+    kind: 'windowed-map';
+    source: CompiledExpressionV3;
+    windowSize: number;
+    windowVar: string;
+    windowBody: CompiledExpressionV3;
+}
+export interface CompiledPairwiseMapV3 {
+    kind: 'pairwise-map';
+    source: CompiledExpressionV3;
+    firstVar: string;
+    secondVar: string;
+    pairBody: CompiledExpressionV3;
+}
+export interface CompiledScanV3 {
+    kind: 'scan';
+    source: CompiledExpressionV3;
+    initialState: CompiledExpressionV3;
+    stateVar: string;
+    elementVar: string;
+    accumulate: CompiledExpressionV3;
+}
+export interface CompiledListItemAtV3 {
+    kind: 'list-item-at';
+    source: CompiledExpressionV3;
+    itemIndex: CompiledExpressionV3;
+}
+export interface CompiledEqualsV3 {
+    kind: 'equals';
+    left: CompiledExpressionV3;
+    right: CompiledExpressionV3;
+}
+export interface CompiledGreaterThanV3 {
+    kind: 'greater-than';
+    left: CompiledExpressionV3;
+    right: CompiledExpressionV3;
+}
+export interface CompiledLessThanV3 {
+    kind: 'less-than';
+    left: CompiledExpressionV3;
+    right: CompiledExpressionV3;
+}
+export interface CompiledGreaterThanOrEqualV3 {
+    kind: 'greater-than-or-equal';
+    left: CompiledExpressionV3;
+    right: CompiledExpressionV3;
+}
+export interface CompiledLessThanOrEqualV3 {
+    kind: 'less-than-or-equal';
+    left: CompiledExpressionV3;
+    right: CompiledExpressionV3;
+}
+export interface CompiledNotV3 {
+    kind: 'not';
+    operand: CompiledExpressionV3;
+}
+export interface CompiledAndV3 {
+    kind: 'and';
+    operands: CompiledExpressionV3[];
+}
+export interface CompiledOrV3 {
+    kind: 'or';
+    operands: CompiledExpressionV3[];
+}
+export interface CompiledContainsV3 {
+    kind: 'contains';
+    haystack: CompiledExpressionV3;
+    needle: CompiledExpressionV3;
+}
+export interface CompiledAbsV3 {
+    kind: 'abs';
+    value: CompiledExpressionV3;
+}
+export interface CompiledNegateV3 {
+    kind: 'negate';
+    value: CompiledExpressionV3;
+}
+export interface CompiledIsReferenceV3 {
+    kind: 'is-reference';
+    check: CompiledExpressionV3;
+}
+export interface CompiledIsEmbeddedV3 {
+    kind: 'is-embedded';
+    check: CompiledExpressionV3;
+}
+export interface CompiledIsListV3 {
+    kind: 'is-list';
+    check: CompiledExpressionV3;
+}
+export interface CompiledStatementObjectV3 {
+    kind: 'statement-object';
+    source: CompiledExpressionV3;
+}
+export type NormalizeKindV3 = 'trim-end';
+export interface CompiledNormalizeV3 {
+    kind: 'normalize';
+    source: CompiledExpressionV3;
+    normKind: NormalizeKindV3;
+}
+export interface CompiledIsSetV3 {
+    kind: 'is-set';
+    check: CompiledExpressionV3;
+}
+export interface CompiledCallFragmentV3 {
+    kind: 'call-fragment';
+    /** The fragment's compiled body, inlined at compile time. */
+    body: CompiledExpressionV3;
+}
+export interface CompiledJoinV3 {
+    kind: 'join';
+    source: CompiledExpressionV3;
+    separator: string;
+}
+export interface CompiledCountV3 {
+    kind: 'count';
+    source: CompiledExpressionV3;
+}
+export interface CompiledSumV3 {
+    kind: 'sum';
+    source: CompiledExpressionV3;
+}
+export interface CompiledMinV3 {
+    kind: 'min';
+    source: CompiledExpressionV3;
+}
+export interface CompiledMaxV3 {
+    kind: 'max';
+    source: CompiledExpressionV3;
+}
+export interface CompiledAverageV3 {
+    kind: 'average';
+    source: CompiledExpressionV3;
+}
+export interface CompiledForEachV3 {
+    kind: 'for-each';
+    source: CompiledExpressionV3;
+    loopVar: string;
+    emit: CompiledExpressionV3;
+}
+export interface CompiledListMapV3 {
+    kind: 'list-map';
+    source: CompiledExpressionV3;
+    loopVar: string;
+    mapBody: CompiledExpressionV3;
+}
+export interface CompiledFilterV3 {
+    kind: 'filter';
+    source: CompiledExpressionV3;
+    loopVar: string;
+    predicate: CompiledExpressionV3;
+}
+export interface CompiledPartitionByV3 {
+    kind: 'partition-by';
+    source: CompiledExpressionV3;
+    loopVar: string;
+    partitionKey: CompiledExpressionV3;
+}
+export interface CompiledDistinctByV3 {
+    kind: 'distinct-by';
+    source: CompiledExpressionV3;
+    loopVar: string;
+    distinctKey: CompiledExpressionV3;
+}

package/dist/transformations/v3/ExpressionEngineV3.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Evaluates a `CompiledExpressionV3` tree against an environment.
+ *
+ * Covers the full v3 Expression hierarchy. Aggregations are strict
+ * about element types — non-numeric elements in a Sum/Min/Max/Average
+ * raise a runtime error. Min/Max/Average on an empty list also error
+ * (per the ontology contract); Sum on empty returns 0; Count works
+ * regardless of element type.
+ *
+ * Property reads walk `statement[]` by canonical predicate URI via
+ * `UriHelpers`. Reference resolution during traversal goes through
+ * the shared `ReferenceResolver`.
+ */
+import { type Kanonak } from '../../kanonaks/index.js';
+import { type EntityUri } from '../../uri-helpers/UriHelpers.js';
+import { ReferenceResolver } from '../ReferenceResolver.js';
+import type { CompiledExpressionV3 } from './CompiledTransformationV3.js';
+/**
+ * Runtime representation of a Partition produced by the
+ * `PartitionBy` expression. Carries the partition key value plus
+ * the list of source elements that share that key.
+ *
+ * The engine surfaces Partitions as plain JS objects; PropertyRead
+ * special-cases this shape so authors can read `partition.key` and
+ * `partition.members` from inside a ForEach over the partition list.
+ */
+export interface RuntimePartitionV3 {
+    kind: 'Partition';
+    key: EnvValue;
+    members: Kanonak[];
+}
+export type EnvValue = string | number | boolean | Kanonak | Kanonak[] | EnvValue[] | RuntimePartitionV3 | EntityUri | unknown | undefined | null;
+export type Env = Map<string, EnvValue>;
+export declare class ExpressionEvalErrorV3 extends Error {
+}
+export declare class ExpressionEngineV3 {
+    private readonly resolver;
+    private readonly catalog;
+    constructor(resolver: ReferenceResolver, catalog: Kanonak[]);
+    evaluate(expr: CompiledExpressionV3, env: Env): Promise<EnvValue>;
+    /**
+     * Evaluate a source expression and coerce its result into a list.
+     * Single-valued results are wrapped in a single-element list so
+     * downstream operations don't have to special-case scalar sources
+     * (e.g. an aggregation over a property that happens to be
+     * single-valued for one instance and multi-valued for another).
+     */
+    private evaluateList;
+    /**
+     * Re-run an iterator with reverse iteration order, preserving each
+     * iteration's body output as a logical group. Returns `undefined`
+     * for non-iterator sources so the caller falls back to flat-list
+     * reversal.
+     *
+     * Why this exists: iterators (PairwiseMap, ForEach, WindowedMap)
+     * flatten array body results into a single output list. Wrapping
+     * one in `tx.Reverse` then applies a flat-list reverse, which
+     * scrambles per-iteration contents (#18). Re-iterating with
+     * reversed source preserves per-iteration body output structure
+     * while delivering the iteration sequence in newest-first order.
+     *
+     * For PairwiseMap, `firstVar` and `secondVar` still bind in
+     * chronological order (earlier→later) so per-pair body semantics
+     * are unchanged — only the visit order of pairs reverses. This
+     * matches the canonical "ascending sortBy + Reverse for newest-
+     * first changelog" idiom from issue #14's worked example.
+     *
+     * ListMap is included even though ListMap doesn't flatten —
+     * Reverse over ListMap should still surface body output in
+     * reverse order, which falling back to flat reversal would do
+     * correctly already; including it here keeps the semantics
+     * consistent (re-iterate with reversed source).
+     */
+    private evaluateReverseIterator;
+}

package/dist/transformations/v3/TransformationLoaderV3.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Compiles a transformations@3.0.0 SubjectKanonak into a typed
+ * CompiledTransformationV3. Walks `statement[]` via the SDK's parsed
+ * object model — never re-parses YAML, never matches on alias
+ * prefixes. Property reads go through `UriHelpers`; type dispatch
+ * uses `hasType` against canonical `TX_V3` URIs.
+ *
+ * Throws `TransformationLoadErrorV3` with a breadcrumb path on the
+ * first shape violation.
+ */
+import { SubjectKanonak, type Kanonak } from '../../kanonaks/index.js';
+import type { CompiledTransformationV3 } from './CompiledTransformationV3.js';
+export declare class TransformationLoadErrorV3 extends Error {
+    readonly path: string;
+    constructor(message: string, path: string);
+}
+/**
+ * Top-level entry point. Determines whether the SubjectKanonak is an
+ * InstanceTransformation or SetTransformation by RDF type, then
+ * dispatches to the appropriate compiler.
+ */
+export declare function compileTransformationV3(transformation: SubjectKanonak, catalog: Kanonak[]): CompiledTransformationV3;

package/dist/transformations/v3/TransformationRunnerV3.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Runtime entry point for transformations@3.0.0.
+ *
+ * Two pipelines:
+ *
+ *   - InstanceTransformation: 1 input → 1 artifact. The runner filters
+ *     candidates by InputPattern, then evaluates `rule` and
+ *     `artifactName` once per candidate with `input` bound. Sort
+ *     order on the InputPattern affects the order of emitted
+ *     artifacts but doesn't change the cardinality.
+ *
+ *   - SetTransformation:
+ *       Without partitionBy: N candidates → 1 artifact, with `inputs`
+ *         bound to the entire matched (and optionally sorted) list.
+ *       With partitionBy: candidates are partitioned by the property
+ *         value; one artifact per partition, with `inputs` bound to
+ *         that partition's members and `key` bound to the partition
+ *         value. Candidates whose partition property is absent are
+ *         dropped (no group is created).
+ *
+ * Sort behavior:
+ *   - SortKey.byProperty is read off each candidate. Missing values
+ *     sort last (ascending) or first (descending). Lists or
+ *     references on the sort property are an authoring error caught
+ *     here at runtime.
+ *
+ * The runner does NOT touch the filesystem — writing is the
+ * deployment handler / CLI's job. Backends are version-agnostic and
+ * shared with any other transformation runtime.
+ */
+import { SubjectKanonak, type Kanonak } from '../../kanonaks/index.js';
+import { KanonakParser, KanonakObjectParser } from '../../parsing/index.js';
+import type { IKanonakDocumentRepository } from '@kanonak-protocol/types/document/models';
+import type { IDocumentAstBackend } from '../backends/IDocumentAstBackend.js';
+import { TransformationLoadErrorV3 } from './TransformationLoaderV3.js';
+import type { CompiledTransformationV3 } from './CompiledTransformationV3.js';
+export interface ArtifactV3 {
+    /** Filename stem (no directory, no extension). */
+    fileName: string;
+    /** OutputFormat local name this was rendered as. */
+    format: string;
+    /** Serialized bytes. */
+    content: string;
+    /** Provenance — which subject(s) drove this artifact. */
+    source: ArtifactProvenanceV3;
+}
+export type ArtifactProvenanceV3 = {
+    kind: 'instance';
+    sourceName: string;
+} | {
+    kind: 'set';
+    memberCount: number;
+    partitionKey?: string;
+};
+export interface FormatDescriptorV3 {
+    formatUri: string;
+    extension: string;
+}
+export declare const SUPPORTED_FORMATS_V3: Record<string, FormatDescriptorV3>;
+export interface RunInputV3 {
+    transformation: SubjectKanonak;
+    /** Candidate input subjects. Caller is responsible for subclass-aware selection. */
+    instances: SubjectKanonak[];
+    /** All loaded kanonaks for fragment lookup + reference resolution. */
+    allKanonaks: Kanonak[];
+    /**
+     * Optional kanonaks of the transformation's own package (where any
+     * ExpressionFragments live). Falls back to allKanonaks.
+     */
+    transformationKanonaks?: Kanonak[];
+    /** Repository for cross-package reference resolution at evaluation time. */
+    repository: IKanonakDocumentRepository;
+    parser: KanonakParser;
+    objectParser: KanonakObjectParser;
+    /** OutputFormat local name (e.g. `'markdown-with-frontmatter'`). */
+    outputFormat: string;
+}
+export declare class TransformationRunnerErrorV3 extends Error {
+}
+export declare class TransformationRunnerV3 {
+    private readonly backends;
+    constructor();
+    register(backend: IDocumentAstBackend): void;
+    run(input: RunInputV3): Promise<ArtifactV3[]>;
+    private runInstance;
+    private runSet;
+    private runSetSingle;
+    private runSetWithPartition;
+    private findBackend;
+}
+export { TransformationLoadErrorV3 };
+export type { CompiledTransformationV3 };