kibi-cli 0.19.0 → 2.0.0

package/dist/operations/mutation/symbol-refresh.js

@@ -1,6 +1,12 @@
-import path from "node:path";
-import { dump as dumpYaml, load as parseYaml } from "js-yaml";
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import * as path from "node:path";
+import { load as parseYaml } from "js-yaml";
+import { CoordinateArtifactError, coarseCoordinateSpan, coordinateIdentityHash, coordinateSourceHash, isValidCoordinateSpan, parseCoordinateArtifact, writeCoordinateArtifact, writeLegacyCoordinateArtifact, } from "../../extractors/symbol-coordinates.js";
 import { enrichSymbolCoordinates } from "../../public/extractors/symbols-coordinator.js";
+import { isCoarseGranularityReason } from "../../public/symbol-granularity.js";
+import { CANONICAL_ENTITY_PATHS } from "../../utils/kb-paths.js";
+import { withSymbolCompilerLock } from "./symbol-compiler-lock.js";
 function record(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -16,90 +22,248 @@ function coordinate(value) {
         ? { sourceFile, sourceLine, sourceColumn, sourceEndLine, sourceEndColumn }
         : null;
 }
-async function exists(context, filePath) {
+async function manifestPath(context) {
+    return path.join(context.workspaceRoot, CANONICAL_ENTITY_PATHS.symbols);
+}
+function artifactPathFor(manifest) {
+    return path.join(path.dirname(manifest), "symbol-coordinates.yaml");
+}
+function sourceTextFor(sourceFile, workspaceRoot) {
+    const absolute = path.isAbsolute(sourceFile)
+        ? sourceFile
+        : path.resolve(workspaceRoot, sourceFile);
+    try {
+        return readFileSync(absolute, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Publish artifact bytes atomically; rename failures clean their temp file and
+ * propagate so callers never advance state on a partial publication.
+ */
+function contentHash(content) {
+    return createHash("sha256").update(content).digest("hex");
+}
+export function restoreOrUnlinkCoordinateArtifact(targetPath, before) {
+    if (before === null) {
+        unlinkSync(targetPath);
+        return;
+    }
+    replaceArtifactAtomically(targetPath, before);
+}
+function replaceArtifactAtomically(targetPath, content) {
+    const temporary = `${targetPath}.kibi-tmp-${process.pid}-${randomUUID()}`;
     try {
-        return context.fs?.stat(filePath).then((stat) => stat.isFile()) ?? false;
+        writeFileSync(temporary, content, "utf8");
+        renameSync(temporary, targetPath);
     }
     catch (error) {
-        if (error instanceof Error)
-            return false;
+        try {
+            unlinkSync(temporary);
+        }
+        catch {
+            // Temp cleanup is best effort; the original failure propagates.
+        }
         throw error;
     }
 }
-async function manifestPath(context) {
+function publishArtifact(targetPath, content) {
+    const before = existsSync(targetPath)
+        ? readFileSync(targetPath, "utf8")
+        : null;
+    const beforeHash = before === null ? null : contentHash(before);
+    const afterHash = contentHash(content);
+    replaceArtifactAtomically(targetPath, content);
+    return {
+        path: targetPath,
+        beforeHash,
+        afterHash,
+        rollback: () => {
+            if (!existsSync(targetPath)) {
+                throw new CoordinateArtifactError(`coordinate artifact disappeared before rollback: ${targetPath}`);
+            }
+            const current = readFileSync(targetPath, "utf8");
+            if (contentHash(current) !== afterHash) {
+                throw new CoordinateArtifactError(`coordinate artifact changed after publication; refusing rollback: ${targetPath}`);
+            }
+            restoreOrUnlinkCoordinateArtifact(targetPath, before);
+        },
+    };
+}
+function writeTargetedArtifact(records, format) {
+    if (format === "v2") {
+        return writeCoordinateArtifact(records);
+    }
+    const legacyRecords = {};
+    for (const [id, entry] of Object.entries(records)) {
+        if (!isValidCoordinateSpan(entry)) {
+            throw new CoordinateArtifactError(`refusing to preserve invalid legacy coordinate span for ${id}`);
+        }
+        legacyRecords[id] = {
+            sourceColumn: entry.sourceColumn,
+            sourceEndColumn: entry.sourceEndColumn,
+            sourceEndLine: entry.sourceEndLine,
+            sourceFile: entry.sourceFile,
+            sourceLine: entry.sourceLine,
+        };
+    }
+    return writeLegacyCoordinateArtifact(legacyRecords);
+}
+/**
+ * Core targeted refresh. Callers must already hold the workspace symbol
+ * compiler lock; the public wrapper acquires it.
+ */
+async function refreshUnlocked(symbolId, context, options = {}) {
     const fs = context.fs;
     if (fs === undefined)
-        return path.join(context.workspaceRoot, "symbols.yaml");
-    const configPath = path.join(context.workspaceRoot, ".kb", "config.json");
+        return { refreshed: false, found: false };
+    const manifest = options.manifestPath ?? (await manifestPath(context));
+    const artifactPath = artifactPathFor(manifest);
+    let parsedManifest;
     try {
-        const config = JSON.parse(await fs.readFile(configPath));
-        if (record(config)) {
-            const paths = config.paths;
-            const configured = record(paths) && typeof paths.symbols === "string"
-                ? paths.symbols
-                : typeof config.symbolsManifest === "string"
-                    ? config.symbolsManifest
-                    : null;
-            if (configured)
-                return path.resolve(context.workspaceRoot, configured);
+        const loadedManifest = parseYaml(await fs.readFile(manifest));
+        if (!record(loadedManifest)) {
+            throw new Error("manifest root is not a mapping");
         }
+        parsedManifest = loadedManifest;
     }
     catch (error) {
-        if (!(error instanceof Error))
-            throw error;
+        throw new Error(`symbol manifest ${manifest} could not be parsed: ${error instanceof Error ? error.message : String(error)}`);
     }
-    for (const name of ["symbols.yaml", "symbols.yml"]) {
-        const candidate = path.join(context.workspaceRoot, name);
-        if (await exists(context, candidate))
-            return candidate;
+    if (!record(parsedManifest) || !Array.isArray(parsedManifest.symbols)) {
+        throw new Error(`symbol manifest ${manifest} has no symbols array`);
     }
-    return path.join(context.workspaceRoot, "symbols.yaml");
-}
-async function defaultRefresh(symbolId, context) {
-    const fs = context.fs;
-    if (fs === undefined)
-        return { refreshed: false, found: false };
-    const manifest = await manifestPath(context);
-    const parsed = parseYaml(await fs.readFile(manifest));
-    if (!record(parsed) || !Array.isArray(parsed.symbols)) {
-        return { refreshed: false, found: false };
+    const entry = parsedManifest.symbols.find((value) => record(value) && value.id === symbolId);
+    // Strictly parse the existing artifact so a malformed compiler dependency
+    // aborts the refresh instead of being truncated to one symbol.
+    let existingRecords = {};
+    let artifactFormat = "v2";
+    if (existsSync(artifactPath)) {
+        const parsedArtifact = parseCoordinateArtifact(await fs.readFile(artifactPath));
+        if (parsedArtifact.status === "invalid") {
+            throw new CoordinateArtifactError(parsedArtifact.reason);
+        }
+        artifactFormat = parsedArtifact.status === "legacy" ? "legacy" : "v2";
+        existingRecords = { ...parsedArtifact.coordinates };
+    }
+    if (!record(entry)) {
+        // The symbol no longer exists in the authored manifest. A standalone
+        // refresh removes its stale generated record so proof fails closed.
+        if (existingRecords[symbolId] === undefined) {
+            return { refreshed: false, found: false, outcome: "not_found" };
+        }
+        delete existingRecords[symbolId];
+        const publication = publishArtifact(artifactPath, writeTargetedArtifact(existingRecords, artifactFormat));
+        return {
+            refreshed: true,
+            found: false,
+            outcome: "removed",
+            publication,
+        };
     }
-    const entry = parsed.symbols.find((value) => record(value) && value.id === symbolId);
-    if (!record(entry))
-        return { refreshed: false, found: false };
     const sourceFile = typeof entry.sourceFile === "string" ? entry.sourceFile : "";
     const title = typeof entry.title === "string" ? entry.title : "";
     const [enriched] = await enrichSymbolCoordinates([{ ...entry, id: symbolId, title, sourceFile }], context.workspaceRoot);
-    const next = coordinate(enriched);
-    if (next === null)
-        return { refreshed: false, found: true };
-    const artifactPath = path.join(path.dirname(manifest), "symbol-coordinates.yaml");
-    let coordinates = {};
-    try {
-        const artifact = parseYaml(await fs.readFile(artifactPath));
-        if (record(artifact) && record(artifact.coordinates)) {
-            coordinates = Object.fromEntries(Object.entries(artifact.coordinates).flatMap(([id, value]) => {
-                const normalized = coordinate(value);
-                return normalized === null ? [] : [[id, normalized]];
-            }));
+    let next = coordinate(enriched);
+    let sourceText = next === null ? sourceTextFor(sourceFile, context.workspaceRoot) : null;
+    if (next === null &&
+        isCoarseGranularityReason(entry.granularity_reason) &&
+        sourceText !== null) {
+        next = coarseCoordinateSpan(sourceFile, title, sourceText);
+    }
+    if (next !== null && sourceText === null) {
+        sourceText = sourceTextFor(next.sourceFile, context.workspaceRoot);
+    }
+    if (next === null || !isValidCoordinateSpan(next)) {
+        // No extractable coordinates: remove stale generated state so proof keeps
+        // failing closed instead of rebinding an old span to current source bytes.
+        if (existingRecords[symbolId] === undefined) {
+            return { refreshed: false, found: true };
         }
+        delete existingRecords[symbolId];
+        const publication = publishArtifact(artifactPath, writeTargetedArtifact(existingRecords, artifactFormat));
+        return {
+            refreshed: true,
+            found: true,
+            outcome: "removed",
+            publication,
+        };
     }
-    catch (error) {
-        if (!(error instanceof Error))
-            throw error;
-    }
-    coordinates[symbolId] = next;
-    const sorted = Object.fromEntries(Object.entries(coordinates).sort(([left], [right]) => left.localeCompare(right)));
-    const content = `# symbol-coordinates.yaml\n# GENERATED coordinate artifact — do not edit manually.\n# Run \`kibi sync --refresh-symbol-coordinates\` to refresh.\n${dumpYaml({ coordinates: sorted }, { lineWidth: -1, noRefs: true, sortKeys: true })}`;
-    await fs.writeFile(artifactPath, content);
-    return { refreshed: true, found: true };
+    if (sourceText === null) {
+        return { refreshed: false, found: true, outcome: "unchanged" };
+    }
+    const identityHash = coordinateIdentityHash({
+        id: symbolId,
+        ...(title === "" ? {} : { title }),
+        ...(sourceFile === "" ? {} : { sourceFile }),
+        ...(typeof entry.granularity_reason === "string"
+            ? { granularity_reason: entry.granularity_reason }
+            : {}),
+    });
+    const bound = {
+        ...next,
+        identityHash,
+        sourceHash: coordinateSourceHash(sourceText),
+    };
+    const previousRecord = existingRecords[symbolId];
+    const sameSpan = previousRecord !== undefined &&
+        isValidCoordinateSpan(previousRecord) &&
+        previousRecord.sourceFile === next.sourceFile &&
+        previousRecord.sourceLine === next.sourceLine &&
+        previousRecord.sourceColumn === next.sourceColumn &&
+        previousRecord.sourceEndLine === next.sourceEndLine &&
+        previousRecord.sourceEndColumn === next.sourceEndColumn;
+    const unchangedBytes = sameSpan &&
+        (artifactFormat === "legacy" ||
+            (previousRecord.identityHash ===
+                identityHash &&
+                previousRecord.sourceHash ===
+                    bound.sourceHash));
+    if (unchangedBytes) {
+        return { refreshed: false, found: true, outcome: "unchanged" };
+    }
+    existingRecords[symbolId] = artifactFormat === "legacy" ? next : bound;
+    const sortedEntries = Object.fromEntries(Object.entries(existingRecords).sort(([left], [right]) => left.localeCompare(right)));
+    const publication = publishArtifact(artifactPath, writeTargetedArtifact(sortedEntries, artifactFormat));
+    return {
+        refreshed: true,
+        found: true,
+        outcome: "updated",
+        publication,
+    };
 }
-let implementation = defaultRefresh;
-// implements REQ-kibi-operation-interface-parity
+let implementation = null;
+/** Targeted coordinate refresh under the workspace symbol compiler lock. */
 export async function refreshSymbolCoordinates(symbolId, context) {
-    return implementation(symbolId, context);
+    const active = implementation ?? refreshUnlocked;
+    if (implementation !== null && implementation !== undefined) {
+        // Test-substituted implementations run without the real filesystem lock.
+        return active(symbolId, context);
+    }
+    return withSymbolCompilerLock(context.workspaceRoot, () => active(symbolId, context));
+}
+/** Run one refresh step without acquiring the lock (caller holds it). */
+// implements REQ-generated-coordinate-persistence
+export async function refreshSymbolCoordinatesUnlocked(symbolId, context) {
+    const active = implementation ?? refreshUnlocked;
+    return active(symbolId, context);
+}
+/**
+ * Refresh against an explicitly authored manifest path (the source-first
+ * write target), not just the canonical lane. Callers hold the compiler lock.
+ */
+// implements REQ-generated-coordinate-persistence
+export async function refreshSymbolCoordinatesForManifest(symbolId, manifestAbsolutePath, context) {
+    if (implementation !== null) {
+        return implementation(symbolId, context);
+    }
+    return refreshUnlocked(symbolId, context, {
+        manifestPath: manifestAbsolutePath,
+    });
 }
 // implements REQ-kibi-operation-interface-parity
 export function setSymbolRefreshForTests(refresh) {
-    implementation = refresh ?? defaultRefresh;
+    implementation = refresh ?? null;
 }

package/dist/operations/mutation/types.d.ts

@@ -5,6 +5,12 @@ export type UpsertInput = {
     readonly id: string;
     readonly properties: Readonly<Record<string, unknown>>;
     readonly relationships?: readonly RelationshipInput[];
+    readonly document?: {
+        /** Workspace-relative authored source target. */
+        readonly path?: string;
+        /** Complete document bytes. Omit to preserve the existing body bytes. */
+        readonly body?: string;
+    };
     readonly _skipContradictionCheck?: boolean;
     readonly _requestId?: string;
 };
@@ -18,6 +24,25 @@ export type UpsertPayload = {
     readonly relationships_created: number;
     readonly warnings: readonly string[];
     readonly semanticAdvisor: SemanticAdvisorReceipt;
+    readonly status?: "committed_with_repairs";
+    readonly effectFailures?: readonly {
+        readonly kind: string;
+        readonly errorCode?: string;
+        readonly detail?: unknown;
+    }[];
+    readonly nextActions?: readonly {
+        readonly operation: string;
+        readonly input?: unknown;
+        readonly reason: string;
+        readonly required: boolean;
+    }[];
+    readonly sourceWrites?: readonly {
+        readonly path: string;
+        readonly mode?: "write" | "delete";
+        readonly beforeHash: string | null;
+        readonly afterHash: string | null;
+        readonly created: boolean;
+    }[];
     readonly contradictionCheck?: {
         readonly outcome: "no-conflict" | "skipped";
         readonly checked_req_id: string;
@@ -32,12 +57,43 @@ export type ValidateUpsertPayload = {
     readonly normalizedPreview: Readonly<Record<string, unknown>> | null;
 };
 export type DeleteInput = {
-    readonly ids: readonly string[];
+    readonly ids?: readonly string[];
+    readonly relationships?: readonly {
+        readonly type: string;
+        readonly from: string;
+        readonly to: string;
+    }[];
     readonly _requestId?: string;
+    readonly approvedPlanHash?: string;
 };
 export type DeletePayload = {
     readonly deleted: number;
+    readonly relationships_deleted?: number;
     readonly skipped: number;
     readonly errors: readonly string[];
+    readonly error_codes?: readonly Readonly<Record<string, unknown>>[];
+    readonly relationship_results?: readonly Record<string, unknown>[];
+    readonly sync_required?: boolean;
+    readonly sourceWrites?: readonly {
+        readonly path: string;
+        readonly mode?: "write" | "delete";
+        readonly beforeHash: string | null;
+        readonly afterHash: string | null;
+        readonly created: boolean;
+    }[];
+    readonly deletionPlan?: {
+        readonly version: "kibi.entity-deletion-plan.v1";
+        readonly planHash: string;
+        readonly entityIds: readonly string[];
+        readonly sourceHashes: Readonly<Record<string, string | null>>;
+        readonly sourceWrites?: readonly {
+            readonly path: string;
+            readonly mode: "write" | "delete";
+            readonly beforeHash: string | null;
+            readonly afterHash: string | null;
+            readonly body?: string;
+        }[];
+        readonly supersessionRequired: boolean;
+    };
 };
 //# sourceMappingURL=types.d.ts.map

package/dist/operations/mutation/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAG3E,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAGlE,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACvD,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACtD,QAAQ,CAAC,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAC3C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B,CAAC;AAGF,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC,QAAQ,CAAC,aAAa,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACtD,CAAC;AAGF,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,eAAe,EAAE,sBAAsB,CAAC;IACjD,QAAQ,CAAC,kBAAkB,CAAC,EAAE;QAC5B,QAAQ,CAAC,OAAO,EAAE,aAAa,GAAG,SAAS,CAAC;QAC5C,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;QAChC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;KACnC,CAAC;CACH,CAAC;AAGF,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,eAAe,EAAE,sBAAsB,GAAG,IAAI,CAAC;IACxD,QAAQ,CAAC,iBAAiB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;CACtE,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/types.ts"],"names":[],"mappings":"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"}

package/dist/operations/mutation/upsert.d.ts

@@ -1,7 +1,23 @@
 import type { OperationContext } from "../../public/operations/runtime-types.js";
 import type { OperationResult } from "../../public/operations/types.js";
 import type { RelationshipInput, UpsertInput, UpsertPayload } from "./types.js";
-export declare function validateAppendOnlyVerificationReceipts(entity: Readonly<Record<string, unknown>>, context: OperationContext): Promise<void>;
+export declare function validateAppendOnlyProofReceipts(entity: Readonly<Record<string, unknown>>, context: OperationContext): Promise<void>;
 export declare function effectiveRelationships(input: UpsertInput, entity: Readonly<Record<string, unknown>>, relationships: readonly RelationshipInput[], context: OperationContext): Promise<readonly RelationshipInput[]>;
-export declare function executeUpsert(input: UpsertInput, context: OperationContext): Promise<OperationResult<UpsertPayload>>;
+export type UpsertExecutionOptions = Readonly<{
+    /**
+     * Internal escape hatch for proof-receipt ingest: when provided, the
+     * authored document is written with exactly these bytes instead of the
+     * canonical re-render. Receipt appends must not canonicalize unrelated
+     * frontmatter — a mid-campaign reformat would change the workspace
+     * snapshot hash and make every later `kibi prove` integration refuse.
+     */
+    readonly sourceDocumentOverride?: string;
+    /**
+     * Internal escape hatch for `kibi proof prune`: the prune maintenance
+     * command deliberately shrinks a test's receipt history to its newest
+     * entries. Everything else keeps the append-only invariant fail-closed.
+     */
+    readonly allowReceiptsPrune?: boolean;
+}>;
+export declare function executeUpsert(input: UpsertInput, context: OperationContext, options?: UpsertExecutionOptions): Promise<OperationResult<UpsertPayload>>;
 //# sourceMappingURL=upsert.d.ts.map

package/dist/operations/mutation/upsert.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"upsert.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/upsert.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AACjF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAgBxE,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AA8BhF,wBAAsB,sCAAsC,CAC1D,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,IAAI,CAAC,CAaf;AAED,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,aAAa,EAAE,SAAS,iBAAiB,EAAE,EAC3C,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC,CAgBvC;AAED,wBAAsB,aAAa,CACjC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,aAAa,CAAC,CAAC,CAuGzC"}
+{"version":3,"file":"upsert.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/upsert.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AACjF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAkCxE,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAuGhF,wBAAsB,+BAA+B,CACnD,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,IAAI,CAAC,CAaf;AAED,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,aAAa,EAAE,SAAS,iBAAiB,EAAE,EAC3C,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC,CAuBvC;AAmCD,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAC5C;;;;;;OAMG;IAEH,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IACzC;;;;OAIG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;CACvC,CAAC,CAAC;AAEH,wBAAsB,aAAa,CACjC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,gBAAgB,EACzB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,eAAe,CAAC,aAAa,CAAC,CAAC,CAsczC"}