Connected Knowledge Assertions

import { assertions } from "@use-crux/core/knowledge";
import type {
  AssertionEmitApi,
  AssertionEmitOptions,
  AssertionIdentityRefInput,
  AssertionListOptions,
  AssertionListPage,
  AssertionOf,
  AssertionRelationListOptions,
  AssertionRef,
  AssertionRelateOptions,
  AssertionRelationRecord,
  AssertionRelationType,
  AssertionResolutionHandle,
  AssertionResolutionPolicy,
  AssertionResolutionResult,
  AssertionResolutionStatus,
  AssertionSet,
  AssertionSetOptions,
  AssertionsConfig,
} from "@use-crux/core/knowledge";

function assertions<const TTypes extends Record<string, z.ZodType<unknown>>>(
  config: AssertionsConfig<TTypes>,
): AssertionStage<TTypes>;

type AssertionsConfig<TTypes extends Record<string, z.ZodType<unknown>>> = {
  readonly id: string;
  readonly version: number;
  readonly types: TTypes;
  readonly targets?: (chunks: readonly CruxChunk[]) => readonly CruxChunk[];
} & (
  | {
      readonly model: KnowledgeModel;
      readonly instructions?: string;
      readonly run?: never;
    }
  | {
      readonly run: AssertionRun<TTypes>;
      readonly model?: never;
      readonly instructions?: never;
    }
);

interface AssertionRunInput {
  readonly document: CruxDocument;
  readonly chunks: readonly CruxChunk[];
  readonly targets: readonly CruxChunk[];
}

interface AssertionEmitOptions {
  readonly evidence: KnowledgeRef | readonly KnowledgeRef[];
  readonly provenance?: "exact" | "derived";
}

interface AssertionEmitApi<TTypes extends Record<string, z.ZodType<unknown>>> {
  emit<TType extends keyof TTypes & string>(
    type: TType,
    data: z.infer<TTypes[TType]>,
    opts: AssertionEmitOptions,
  ): AssertionRef;
  relate(
    type: AssertionRelationType,
    from: AssertionRelationEndpoint<TTypes>,
    to: AssertionRelationEndpoint<TTypes>,
    opts: AssertionRelateOptions,
  ): void;
}

import { z } from "zod";
import { assertions } from "@use-crux/core/knowledge";

const facts = assertions({
  id: "commercial-facts",
  version: 1,
  types: {
    price: z.object({
      amount: z.number(),
      currency: z.string(),
    }),
  },
  run: (_input, api) => {
    api.emit(
      "price",
      { amount: 12, currency: "EUR" },
      {
        evidence: { kind: "chunk", sourceId: "pricing", chunkId: "main" },
        provenance: "exact",
      },
    );
  },
});

interface AssertionSet<TTypes, TSelected = keyof TTypes & string> {
  readonly _tag: "AssertionSet";
  readonly id: string;
  readonly namespace: string;
  list(options?: AssertionListOptions): Promise<AssertionListPage<AssertionOf<TTypes, TSelected>>>;
  stream(): AsyncIterable<AssertionOf<TTypes, TSelected>>;
  relations(options?: AssertionRelationListOptions): Promise<AssertionListPage<AssertionRelationRecord>>;
  resolve(policy?: AssertionResolutionPolicy<TTypes, TSelected>): AssertionResolutionHandle<TTypes, TSelected>;
  asContext(options?: AssertionContextOptions): Context<z.ZodType<{}>>;
  inject(args: { input: Record<string, unknown>; promptId?: string }): Promise<InternalPromptInjection>;
}

interface AssertionListPage<TItem> {
  readonly items: readonly TItem[];
  readonly cursor?: string;
}

type AssertionOf<TTypes, K = keyof TTypes> = {
  readonly assertionId: string;
  readonly type: K;
  readonly data: z.infer<TTypes[K]>;
  readonly evidence: readonly AssertionSupport[];
  readonly provenance: "exact" | "derived";
};

const set = docs.assertions(facts, { types: ["price"] });
const page = await set.list({ limit: 10 });

for (const item of page.items) {
  console.log(item.type, item.data);
}

interface AssertionResolutionHandle<TTypes, TSelected> {
  readonly _tag: "AssertionResolution";
  readonly id: string;
  status(): Promise<AssertionResolutionStatus>;
  prepare(): Promise<void>;
  result(): Promise<AssertionResolutionResult<AssertionOf<TTypes, TSelected>>>;
  asContext(options?: AssertionContextOptions): Context<z.ZodType<{}>>;
  inject(args: { input: Record<string, unknown>; promptId?: string }): Promise<InternalPromptInjection>;
}

interface AssertionResolutionStatus {
  readonly state: "idle" | "ready";
  readonly cached: boolean;
  readonly generationId?: string;
  readonly revisionHash?: string;
}

interface AssertionResolutionResult<TItem> {
  readonly selected: readonly TItem[];
  readonly superseded: readonly TItem[];
  readonly contested: readonly TItem[];
  readonly unresolved: readonly TItem[];
  readonly trace: readonly AssertionResolutionTrace[];
}

type AssertionDecisionEvidence =
  | {
      readonly kind: "relation";
      readonly relationId: string;
      readonly type: AssertionRelationType;
      readonly evidence: readonly AssertionSupport[];
      readonly provenance: "exact" | "derived";
      readonly stageId: string;
      readonly stageVersion: number;
      readonly stageFingerprint: string;
    }
  | {
      readonly kind: "policy";
      readonly policyId: string;
      readonly note?: string;
    };

type AssertionResolutionPolicy<TTypes, TSelected> =
  | {
      readonly id: string;
      readonly version: number;
      readonly model: KnowledgeModel;
      readonly instructions?: string;
      readonly run?: never;
    }
  | {
      readonly id: string;
      readonly version: number;
      readonly run: (
        input: AssertionPolicyInput<AssertionOf<TTypes, TSelected>>,
        decision: AssertionPolicyDecision<AssertionOf<TTypes, TSelected>>,
      ) => void | Promise<void>;
      readonly model?: never;
      readonly instructions?: never;
    };

const resolution = docs.assertions(facts).resolve({
  id: "prefer-latest",
  version: 1,
  run: ({ assertions }, decision) => {
    for (const assertion of assertions) {
      decision.select(assertion, "Accepted by deterministic policy.");
    }
  },
});

const result = await resolution.result();
console.log(result.selected.length);

interface AssertionRef extends JsonObject {
  readonly assertionId: string;
}

type AssertionRelationType =
  | "supports"
  | "amends"
  | "supersedes"
  | "narrows"
  | "conflictsWith";

interface AssertionIdentityRefInput<TType extends string = string, TData = unknown> {
  readonly type: TType;
  readonly data: TData;
}