@kanonak-protocol/sdk 3.5.0 → 3.6.0

package/dist/derivation/findDerivation.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Polymorphic derivation discovery.
+ *
+ * Given an instance, a target format, and a target variant, walks the
+ * Kanonak ontology to find the transformation that should produce
+ * that derived artifact. The walk respects the protocol's two-level
+ * override semantics:
+ *
+ *   1. **Per-instance override (replace):** if the instance itself
+ *      declares `derivation.derivations`, those are the ONLY bindings
+ *      considered. The instance takes full ownership; class-level
+ *      bindings do not fall through.
+ *
+ *   2. **Class-hierarchy walk (merge by format+variant):** otherwise,
+ *      the walk starts from the instance's declared type and ascends
+ *      via `rdfs.subClassOf` chains. The closest class wins for any
+ *      given (format, variant) pair. Different (format, variant)
+ *      pairs may be sourced from different classes in the chain —
+ *      one class can override `html/default` while inheriting
+ *      `markdown/summary` from its parent.
+ *
+ *   3. **Universal default (the floor):** the universal-derivations
+ *      package augments `rdfs.Resource` with bindings for
+ *      `formats.html`, `formats.markdown`, and `formats.json`. The
+ *      open-world parser merges those into `rdfs.Resource`'s
+ *      canonical Subject, so the walk discovers them when it reaches
+ *      the root of every type chain.
+ *
+ * Returns `undefined` when no binding is found — failure is visible,
+ * never silently filled (per the no-mocks/no-fallbacks rule).
+ */
+import { SubjectKanonak } from '../kanonaks/index.js';
+import type { Kanonak } from '../kanonaks/index.js';
+/**
+ * Canonical URI identity (publisher + package + name). Version is
+ * intentionally omitted from the comparison API — discovery looks up
+ * resources by their stable identity, not by version.
+ */
+export interface DerivationEntityUri {
+    publisher: string;
+    package_: string;
+    name: string;
+}
+/**
+ * The 4-tuple identifying a published transformation. Resolved later
+ * by the runtime against a repository to fetch the actual
+ * `SubjectKanonak`.
+ */
+export interface TransformationReferenceTuple {
+    publisher: string;
+    package_: string;
+    version: string;
+    name: string;
+}
+/**
+ * The result of a successful discovery — the transformation pointer
+ * plus provenance (where in the hierarchy the binding was found).
+ */
+export interface DerivationLookupResult {
+    /** Pointer to the transformation that produces the artifact. */
+    transformation: TransformationReferenceTuple;
+    /**
+     * Where the binding was sourced from:
+     *   - 'instance': the resource declared its own derivations.
+     *   - {publisher, package_, name}: the class (somewhere in the
+     *     hierarchy) that supplied the binding. `rdfs.Resource` here
+     *     means the universal default applied.
+     */
+    source: 'instance' | DerivationEntityUri;
+}
+/**
+ * Discover the transformation that should produce a derived artifact
+ * of the given (format, variant) for an instance.
+ *
+ * @param instance The Kanonak resource being derived.
+ * @param format Canonical URI of the target Format instance (typically
+ *               from `kanonak.org/formats@1.0.0`).
+ * @param variant Canonical URI of the target Variant instance
+ *                (typically from `kanonak.org/derivation@1.0.0`).
+ * @param catalog All loaded kanonaks (parsed via `KanonakObjectParser`).
+ *                Should include the instance's class hierarchy AND
+ *                `kanonak.org/universal-derivations@1.0.0` if you
+ *                want the universal defaults to apply.
+ */
+export declare function findDerivation(instance: SubjectKanonak, format: DerivationEntityUri, variant: DerivationEntityUri, catalog: Kanonak[]): DerivationLookupResult | undefined;

package/dist/derivation/index.d.ts

@@ -0,0 +1,2 @@
+export { findDerivation } from './findDerivation.js';
+export type { DerivationEntityUri, TransformationReferenceTuple, DerivationLookupResult, } from './findDerivation.js';

package/dist/index.d.ts

@@ -23,5 +23,7 @@ export { CredentialStore, createAuthenticatedFetch, generateDPoPKeyPair, createD
 export type { CredentialBackend, StoredCredential, DPoPKeyPair, AuthenticatedFetchFn, } from './auth/index.js';
 export { loadLockFile, saveLockFile, computeIntegrity, } from './lock/index.js';
 export type { LockFile, LockEntry } from './lock/index.js';
+export { findDerivation } from './derivation/index.js';
+export type { DerivationEntityUri, TransformationReferenceTuple, DerivationLookupResult, } from './derivation/index.js';
 export { CtlKanonakUri, CtlParser, ResourceTypeClassifier, CtlValidator, CtlGraphResolver, CtlMarkdownRenderer, CtlValidationErrorType, CtlValidationSeverity, CtlKanonakUriType, PathSegmentType, ResolvedResourceType } from './ctl/index.js';
 export type { CtlDocument, KanonakReference, CtlValidationResult, CtlValidationError, ResolvedResourceGraph, ResolvedResource, ResolvedProperty, UnresolvedResource } from './ctl/index.js';