@opendatalabs/personal-server-ts-core 1.33.8 → 1.34.0

package/dist/storage/pdpp-records/declaration-witness.js

@@ -0,0 +1,230 @@
+import { createCipheriv, createDecipheriv, createHash, randomBytes, } from "node:crypto";
+import { decodeCursor, InvalidCursorSyntaxError } from "./cursor.js";
+import { compileRecordSchema, redactedPath } from "./schema.js";
+import { CursorExpiredError, InvalidCursorError, } from "./types.js";
+export class DeclarationWitnessInputError extends Error {
+    constructor() {
+        super("Declaration witness requires a source, stream and positive safe-integer limit");
+        this.name = "DeclarationWitnessInputError";
+    }
+}
+export class DeclarationWitnessSchemaError extends Error {
+    constructor() {
+        // Do not attach Ajv errors or schema text to a public error.
+        super("Declaration witness schema cannot be compiled synchronously");
+        this.name = "DeclarationWitnessSchemaError";
+    }
+}
+export class DeclarationWitnessCursorError extends InvalidCursorError {
+    constructor() {
+        super("Declaration witness cursor is invalid, expired or belongs to another walk");
+        this.name = "DeclarationWitnessCursorError";
+    }
+}
+export class DeclarationWitnessReadError extends Error {
+    constructor() {
+        super("Declaration witness read port returned an invalid page");
+        this.name = "DeclarationWitnessReadError";
+    }
+}
+// The ordinary list cursor is unsigned and not instance/schema-bound.
+// Encrypt/authenticate it without changing its bytes or retaining one entry
+// per page. Weak keys allow ports and their secrets to be garbage-collected.
+// Tokens resume only with the same port object in the same process.
+const cursorKeys = new WeakMap();
+const prefix = "dw1.";
+function sealCursor(port, cursor, context) {
+    let key = cursorKeys.get(port);
+    if (!key) {
+        key = randomBytes(32);
+        cursorKeys.set(port, key);
+    }
+    const iv = randomBytes(12);
+    const cipher = createCipheriv("aes-256-gcm", key, iv);
+    cipher.setAAD(Buffer.from(context, "utf8"));
+    const encrypted = Buffer.concat([
+        cipher.update(cursor, "utf8"),
+        cipher.final(),
+    ]);
+    return (prefix +
+        Buffer.concat([iv, cipher.getAuthTag(), encrypted]).toString("base64url"));
+}
+function openCursor(port, token, context) {
+    try {
+        const key = cursorKeys.get(port);
+        if (!key || !token.startsWith(prefix))
+            throw new DeclarationWitnessCursorError();
+        const encoded = token.slice(prefix.length);
+        if (!/^[A-Za-z0-9_-]+$/.test(encoded))
+            throw new DeclarationWitnessCursorError();
+        const bytes = Buffer.from(encoded, "base64url");
+        if (bytes.length <= 28 || bytes.toString("base64url") !== encoded) {
+            throw new DeclarationWitnessCursorError();
+        }
+        const decipher = createDecipheriv("aes-256-gcm", key, bytes.subarray(0, 12));
+        decipher.setAAD(Buffer.from(context, "utf8"));
+        decipher.setAuthTag(bytes.subarray(12, 28));
+        return Buffer.concat([
+            decipher.update(bytes.subarray(28)),
+            decipher.final(),
+        ]).toString("utf8");
+    }
+    catch {
+        throw new DeclarationWitnessCursorError();
+    }
+}
+/** Check the store's existing cursor contract; never manufacture a position. */
+function storePosition(cursor, stream) {
+    const payload = decodeCursor(cursor);
+    if (payload.kind !== "list" ||
+        payload.stream !== stream ||
+        typeof payload.epoch !== "string" ||
+        payload.order !== "asc" ||
+        (payload.sortValue !== null && typeof payload.sortValue !== "string") ||
+        typeof payload.recordKey !== "string" ||
+        (payload.horizon !== undefined && typeof payload.horizon !== "string")) {
+        throw new DeclarationWitnessCursorError();
+    }
+    return payload;
+}
+/**
+ * Validate one bounded page of a declaration-upgrade walk.
+ *
+ * A partial result certifies only the rows already visited. A pass means the
+ * read port reported its terminal page and all visited live rows validated.
+ * The read port is NOT a snapshot: inserts behind the cursor, updates and
+ * deletes can change what the walk observes. The caller MUST keep writes and
+ * resets quiescent (or supply a snapshot-backed port) for the entire walk
+ * through the upgrade decision. This API supplies no mutation fence.
+ *
+ * sourceKey is exactly one instance ID, avoiding cross-instance tuple ties.
+ * Continuations are opaque, encrypted/authenticated, and scoped to the same
+ * port object/process, source, stream and JSON-serialized nextSchema. Restart
+ * the walk after recreating a port, restarting the process or changing the
+ * schema. A retry may reuse a cursor; the port's live-read caveat still applies.
+ * No record data, raw keys, schema contents or validator messages are logged
+ * or returned. Array indices and schema-declared property names may appear
+ * in the redacted failure pointer.
+ */
+export async function witnessDeclarationUpgrade({ readPort, sourceKey, stream, nextSchema, cursor, limit, }) {
+    if (!Number.isSafeInteger(limit) ||
+        limit <= 0 ||
+        typeof sourceKey !== "string" ||
+        sourceKey.length === 0 ||
+        typeof stream !== "string" ||
+        stream.length === 0) {
+        throw new DeclarationWitnessInputError();
+    }
+    let schema;
+    let validate;
+    let schemaDigest;
+    try {
+        // Keep schema compilation, fingerprinting and path redaction on the same
+        // object even if the caller mutates its schema while listRecords awaits.
+        schema = structuredClone(nextSchema);
+        validate = compileRecordSchema(schema);
+        if ("$async" in validate && validate.$async)
+            throw new DeclarationWitnessSchemaError();
+        schemaDigest = createHash("sha256")
+            .update(JSON.stringify(schema))
+            .digest("hex");
+    }
+    catch {
+        throw new DeclarationWitnessSchemaError();
+    }
+    const context = JSON.stringify([prefix, sourceKey, stream, schemaDigest]);
+    let storeCursor;
+    if (cursor !== undefined) {
+        storeCursor = openCursor(readPort, cursor, context);
+        try {
+            storePosition(storeCursor, stream);
+        }
+        catch {
+            throw new DeclarationWitnessCursorError();
+        }
+    }
+    let page;
+    try {
+        page = await readPort.listRecords(stream, {
+            instanceIds: [sourceKey],
+            order: "asc",
+            limit,
+            ...(storeCursor === undefined ? {} : { cursor: storeCursor }),
+        });
+    }
+    catch (error) {
+        if (error instanceof InvalidCursorError ||
+            error instanceof InvalidCursorSyntaxError ||
+            error instanceof CursorExpiredError) {
+            throw new DeclarationWitnessCursorError();
+        }
+        // A bridge may include row contents in an error. Do not expose its cause.
+        throw new DeclarationWitnessReadError();
+    }
+    if (!page ||
+        !Array.isArray(page.data) ||
+        page.data.length > limit ||
+        typeof page.hasMore !== "boolean" ||
+        (!page.hasMore && page.nextCursor !== undefined)) {
+        throw new DeclarationWitnessReadError();
+    }
+    if (page.hasMore) {
+        try {
+            if (!page.nextCursor ||
+                page.nextCursor === storeCursor ||
+                page.data.length === 0) {
+                throw new DeclarationWitnessReadError();
+            }
+            const position = storePosition(page.nextCursor, stream);
+            const last = page.data[page.data.length - 1];
+            if (!last ||
+                position.recordKey !== last.recordKey ||
+                position.sortValue !== last.emittedAt) {
+                throw new DeclarationWitnessReadError();
+            }
+        }
+        catch {
+            throw new DeclarationWitnessReadError();
+        }
+    }
+    let checked = 0;
+    for (const row of page.data) {
+        if (!row ||
+            row.instance !== sourceKey ||
+            row.stream !== stream ||
+            typeof row.recordKey !== "string" ||
+            (row.deleted !== true && row.deleted !== false)) {
+            throw new DeclarationWitnessReadError();
+        }
+        // listRecords excludes tombstones by contract; defend against adapters
+        // that return them anyway without validating their absent data.
+        if (row.deleted)
+            continue;
+        checked += 1;
+        if (!validate(row.data)) {
+            const [error] = validate.errors ?? [];
+            return {
+                verdict: "fail",
+                checked,
+                nextCursor: null,
+                failure: {
+                    recordKeyDigest: createHash("sha256")
+                        .update(row.recordKey)
+                        .digest("hex"),
+                    instancePath: error?.instancePath
+                        ? redactedPath(schema, error.instancePath, row.data)
+                        : "",
+                    keyword: error?.keyword ?? "schema",
+                },
+            };
+        }
+    }
+    return page.hasMore
+        ? {
+            verdict: "partial",
+            checked,
+            nextCursor: sealCursor(readPort, page.nextCursor, context),
+        }
+        : { verdict: "pass", checked, nextCursor: null };
+}
+//# sourceMappingURL=declaration-witness.js.map

package/dist/storage/pdpp-records/declaration-witness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"declaration-witness.js","sourceRoot":"","sources":["../../../src/storage/pdpp-records/declaration-witness.ts"],"names":[],"mappings":"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"}

package/dist/storage/pdpp-records/enforcement.d.ts

@@ -0,0 +1,52 @@
+import { PdppError } from "../../errors/pdpp-catalog.js";
+import { type PdppTokenContext, type StreamGrant } from "../../ports/pdpp-auth.js";
+import { type StreamDeclaration } from "./stream-declaration.js";
+/**
+ * Resolves a request-time authorization context to the effective read
+ * parameters this lane's PdppRecordStore calls need — `instanceIds`,
+ * `fields` — and validates the request against the grant/subject scope. This
+ * is the single narrow chokepoint every §8 read endpoint calls through, so
+ * enforcement logic (and any future grant-shape change) lives in one place.
+ *
+ * Throws PdppError for every documented spec §8 failure mode. Never returns
+ * a widened scope: on ambiguity, the narrower (deny) reading wins.
+ */
+export interface ResolvedReadScope {
+    instanceIds: string[];
+    fields?: string[];
+    streamGrant?: StreamGrant;
+    /**
+     * Whether the declaration's schema-required fields are part of this scope's
+     * disclosure floor.
+     *
+     * True under a v0.1 grant, where §8's per-stream consent floor keeps
+     * schema-required fields in every projection. False under a v0.2 grant,
+     * where the disclosed members are exactly what the grant approved and a
+     * field must not be added "merely because the schema requires it".
+     *
+     * Carried on the scope rather than recomputed at each call site so the two
+     * revisions cannot drift apart between the list read, the single-record
+     * read, and the stream-metadata projection — three places that must agree
+     * about what a grant discloses.
+     */
+    schemaRequiredFloor: boolean;
+}
+export declare function resolveReadScope(context: PdppTokenContext, stream: string, declaration: StreamDeclaration | undefined): ResolvedReadScope;
+/**
+ * Validates that a record's time field satisfies the grant's frozen
+ * time_constraint, if any. Callers filter store results through this before
+ * returning them (the store itself is time_constraint-agnostic).
+ */
+export declare function recordWithinGrantTimeConstraint(data: Record<string, unknown>, streamGrant: StreamGrant | undefined): boolean;
+/** Validates a canonical record_key is within the grant's `resources` allowlist, if constrained. */
+export declare function recordKeyWithinGrantResources(recordKey: string, streamGrant: StreamGrant | undefined): boolean;
+/**
+ * The PdppError an inactive token maps to.
+ *
+ * Exported so every route answers an inactive token with the SAME reason.
+ * `/v1/streams` previously inlined a flat `authentication_error` while record
+ * reads used this mapping, so one revoked grant produced a 401 on one endpoint
+ * and a 403 `grant_revoked` on another.
+ */
+export declare function mapInactiveToError(context: PdppTokenContext): PdppError;
+//# sourceMappingURL=enforcement.d.ts.map

package/dist/storage/pdpp-records/enforcement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enforcement.d.ts","sourceRoot":"","sources":["../../../src/storage/pdpp-records/enforcement.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AACzD,OAAO,EAIL,KAAK,gBAAgB,EACrB,KAAK,WAAW,EACjB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,yBAAyB,CAAC;AAEjC;;;;;;;;;GASG;AACH,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;;;;;;;;;;;;OAaG;IACH,mBAAmB,EAAE,OAAO,CAAC;CAC9B;AAED,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,gBAAgB,EACzB,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,iBAAiB,GAAG,SAAS,GACzC,iBAAiB,CA4FnB;AAED;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC7C,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,WAAW,EAAE,WAAW,GAAG,SAAS,GACnC,OAAO,CAOT;AAED,oGAAoG;AACpG,wBAAgB,6BAA6B,CAC3C,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,WAAW,GAAG,SAAS,GACnC,OAAO,CAGT;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,gBAAgB,GAAG,SAAS,CAevE"}

package/dist/storage/pdpp-records/enforcement.js

@@ -0,0 +1,116 @@
+import { PdppError } from "../../errors/pdpp-catalog.js";
+import { findStreamGrant, grantIsV02, withinTimeConstraint, } from "../../ports/pdpp-auth.js";
+import { withRequiredFields, } from "./stream-declaration.js";
+export function resolveReadScope(context, stream, declaration) {
+    if (!context.active) {
+        throw mapInactiveToError(context);
+    }
+    if (!declaration) {
+        throw new PdppError("not_found", `Stream '${stream}' not found`);
+    }
+    if (context.tokenKind === "owner") {
+        // Owner tokens carry no grant: full current-capability read, but still
+        // scoped to the owner's own subject — enforced by the caller passing
+        // only that subject's instance_ids into the store query, which for the
+        // owner-token case is "every instance belonging to subjectId". This
+        // module doesn't own instance-to-subject resolution (that's the RS
+        // route layer's data-store lookup); it returns `undefined` fields (no
+        // projection restriction) since an owner token has no grant field list.
+        // An owner token has no grant and so no projection to floor: the owner
+        // reads their own records whole.
+        return { instanceIds: [], fields: undefined, schemaRequiredFloor: false };
+    }
+    // Client token: requires an active resolved grant.
+    if (!context.grant) {
+        throw new PdppError("grant_invalid", "Client token has no resolved grant");
+    }
+    const streamGrant = findStreamGrant(context.grant, stream);
+    if (!streamGrant) {
+        throw new PdppError("grant_stream_not_allowed", `Grant does not include stream '${stream}'`);
+    }
+    if (streamGrant.fields.length === 0 ||
+        streamGrant.instance_ids.length === 0) {
+        // Per the AS contract: "If the RS finds ... an empty `fields`, or an
+        // empty `instance_ids`, that is an AS bug — fail closed."
+        throw new PdppError("grant_invalid", "Resolved grant is malformed (empty fields or instance_ids)");
+    }
+    // v0.2 reverses v0.1's consent floor. Under v0.1 the declaration's
+    // required fields are re-added here, so a record is never disclosed in a
+    // shape its own schema would reject. Under v0.2 that is a disclosure bug:
+    // the AS deliberately resolves a grant WITHOUT a schema-required field the
+    // owner did not approve, and re-adding it from the declaration undoes that
+    // narrowing one layer below the decision the owner actually made.
+    const schemaRequiredFloor = !grantIsV02(context.grant);
+    // v0.2 only: can this RS actually serve the projection the grant approved?
+    //
+    // The retained declaration is the RS's only authority for what a record of
+    // this stream means. A granted member the declaration does not declare has
+    // no meaning the RS can stand behind: omitting it asserts "no such value"
+    // (unknown), nulling it is forbidden outright by `v0.2-4-3`, and serving
+    // whatever the record carries under that key discloses an undeclared member
+    // — which is repairing the projection with unauthorized data.
+    //
+    // So refuse, with the code the spec reserves for exactly this. The
+    // distinction from `grant_invalid` is the client's remedy: the grant is
+    // well-formed and this RS cannot serve it, so the answer is to reauthorize
+    // against the current declaration, not to treat the grant as corrupt.
+    //
+    // Checked here rather than at each endpoint because all three client read
+    // surfaces (list, single record, stream metadata) resolve through this
+    // function, and a refusal one of them forgot would be a surface that
+    // discloses what the other two refuse.
+    if (!schemaRequiredFloor && declaration.declaredFields) {
+        const declared = new Set(declaration.declaredFields);
+        const undeclared = streamGrant.fields.filter((f) => !declared.has(f));
+        if (undeclared.length > 0) {
+            throw new PdppError("disclosure_unavailable", `Grant authorizes ${undeclared.join(", ")} on stream '${stream}', which the retained declaration does not declare; the projection cannot be served without disclosing an undeclared member`);
+        }
+    }
+    return {
+        instanceIds: streamGrant.instance_ids,
+        fields: schemaRequiredFloor
+            ? withRequiredFields(streamGrant.fields, declaration.requiredFields)
+            : [...streamGrant.fields],
+        streamGrant,
+        schemaRequiredFloor,
+    };
+}
+/**
+ * Validates that a record's time field satisfies the grant's frozen
+ * time_constraint, if any. Callers filter store results through this before
+ * returning them (the store itself is time_constraint-agnostic).
+ */
+export function recordWithinGrantTimeConstraint(data, streamGrant) {
+    if (!streamGrant?.time_constraint)
+        return true;
+    const value = data[streamGrant.time_constraint.field];
+    return withinTimeConstraint(typeof value === "string" ? value : undefined, streamGrant.time_constraint);
+}
+/** Validates a canonical record_key is within the grant's `resources` allowlist, if constrained. */
+export function recordKeyWithinGrantResources(recordKey, streamGrant) {
+    if (!streamGrant?.resources)
+        return true; // absent = all records
+    return streamGrant.resources.includes(recordKey);
+}
+/**
+ * The PdppError an inactive token maps to.
+ *
+ * Exported so every route answers an inactive token with the SAME reason.
+ * `/v1/streams` previously inlined a flat `authentication_error` while record
+ * reads used this mapping, so one revoked grant produced a 401 on one endpoint
+ * and a 403 `grant_revoked` on another.
+ */
+export function mapInactiveToError(context) {
+    switch (context.inactiveReason) {
+        case "grant_revoked":
+            return new PdppError("grant_revoked", "Grant has been revoked");
+        case "grant_expired":
+            return new PdppError("grant_expired", "Grant has expired");
+        case "expired":
+        case "revoked":
+        case "unknown":
+        default:
+            return new PdppError("authentication_error", "Missing or invalid access token");
+    }
+}
+//# sourceMappingURL=enforcement.js.map

package/dist/storage/pdpp-records/enforcement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"enforcement.js","sourceRoot":"","sources":["../../../src/storage/pdpp-records/enforcement.ts"],"names":[],"mappings":"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"}

package/dist/storage/pdpp-records/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./portable.js";
+export * from "./memory-store.js";
+export * from "./declaration-witness.js";
+export * from "./read-port.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/storage/pdpp-records/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/storage/pdpp-records/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,gBAAgB,CAAC"}

package/dist/storage/pdpp-records/index.js

@@ -0,0 +1,5 @@
+export * from "./portable.js";
+export * from "./memory-store.js";
+export * from "./declaration-witness.js";
+export * from "./read-port.js";
+//# sourceMappingURL=index.js.map

package/dist/storage/pdpp-records/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/storage/pdpp-records/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,gBAAgB,CAAC"}

package/dist/storage/pdpp-records/ingest-plan.d.ts

@@ -0,0 +1,39 @@
+import type { IngestOutcome, IngestResult, PdppRecordEnvelopeInput, StreamSemantics } from "./types.js";
+/** The stored state of a key that decides an envelope's outcome. */
+export interface CurrentContent {
+    deleted: boolean;
+    data: Record<string, unknown> | null;
+}
+/**
+ * What one envelope should do to the store. Both backends call this so they
+ * cannot disagree about outcomes; each only performs the write.
+ *
+ * Content is `deleted` plus the canonical JSON of `data`. `emitted_at` is
+ * version metadata, not content: re-emitting equal content is `unchanged`
+ * and keeps the stored `emitted_at`, so a full refresh of unchanged data
+ * writes no history and wakes no `changes_since` reader.
+ */
+export type IngestPlan = {
+    outcome: IngestOutcome;
+    write?: undefined;
+} | {
+    outcome: {
+        index: number;
+        outcome: "accepted";
+    };
+    write: {
+        recordKey: string;
+        data: Record<string, unknown> | null;
+    };
+};
+/**
+ * Checks upsert `data` against the stream's declared schema (P5). Returns the
+ * rejection reason, or null when the data conforms.
+ */
+export type RecordDataValidator = (stream: string, instance: string, data: Record<string, unknown>) => string | null;
+export declare function planIngest(index: number, envelope: PdppRecordEnvelopeInput, semantics: StreamSemantics, primaryKey: string[], current: (recordKey: string) => CurrentContent | undefined, validateData?: RecordDataValidator): IngestPlan;
+/** JSON with object keys sorted at every depth. */
+export declare function canonicalJson(value: unknown): string;
+/** The per-index outcomes plus the counts callers already read. */
+export declare function summarizeIngest(results: IngestOutcome[]): IngestResult;
+//# sourceMappingURL=ingest-plan.d.ts.map

package/dist/storage/pdpp-records/ingest-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingest-plan.d.ts","sourceRoot":"","sources":["../../../src/storage/pdpp-records/ingest-plan.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,aAAa,EACb,YAAY,EACZ,uBAAuB,EACvB,eAAe,EAChB,MAAM,YAAY,CAAC;AAEpB,oEAAoE;AACpE,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CACtC;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,UAAU,GAClB;IAAE,OAAO,EAAE,aAAa,CAAC;IAAC,KAAK,CAAC,EAAE,SAAS,CAAA;CAAE,GAC7C;IACE,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,UAAU,CAAA;KAAE,CAAC;IAChD,KAAK,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;KAAE,CAAC;CACpE,CAAC;AAEN;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAChC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC1B,MAAM,GAAG,IAAI,CAAC;AAEnB,wBAAgB,UAAU,CACxB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,uBAAuB,EACjC,SAAS,EAAE,eAAe,EAC1B,UAAU,EAAE,MAAM,EAAE,EACpB,OAAO,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,cAAc,GAAG,SAAS,EAC1D,YAAY,CAAC,EAAE,mBAAmB,GACjC,UAAU,CAyEZ;AAED,mDAAmD;AACnD,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEpD;AAcD,mEAAmE;AACnE,wBAAgB,eAAe,CAAC,OAAO,EAAE,aAAa,EAAE,GAAG,YAAY,CAUtE"}

package/dist/storage/pdpp-records/ingest-plan.js

@@ -0,0 +1,103 @@
+import { encodeRecordKey, keyMatchesData, RecordKeyError, } from "./record-key.js";
+export function planIngest(index, envelope, semantics, primaryKey, current, validateData) {
+    const reject = (reason) => ({
+        outcome: { index, outcome: "rejected", reason },
+    });
+    const unchanged = (flag) => ({
+        outcome: { index, outcome: "unchanged", ...(flag && { flag }) },
+    });
+    if (typeof envelope.emitted_at !== "string" || !envelope.emitted_at) {
+        return reject("emitted_at must be a non-empty string");
+    }
+    // JSON `null` means absent, like a missing field: Desktop's blob host
+    // serializes `Option::None` as `"op": null`. Absent `op` is an upsert.
+    if (envelope.op != null &&
+        envelope.op !== "upsert" &&
+        envelope.op !== "delete") {
+        return reject("op must be 'upsert' or 'delete'");
+    }
+    let recordKey;
+    try {
+        recordKey = encodeRecordKey(envelope.key);
+    }
+    catch (err) {
+        if (err instanceof RecordKeyError)
+            return reject(err.message);
+        throw err;
+    }
+    const existing = current(recordKey);
+    if (envelope.op === "delete") {
+        if (semantics === "append_only") {
+            return reject("append_only streams do not support delete directives");
+        }
+        if (!existing || existing.deleted)
+            return unchanged();
+        return {
+            outcome: { index, outcome: "accepted" },
+            write: { recordKey, data: null },
+        };
+    }
+    const data = envelope.data;
+    if (data === null || typeof data !== "object" || Array.isArray(data)) {
+        return reject("data must be a JSON object for upsert");
+    }
+    try {
+        if (!keyMatchesData(envelope.key, data, primaryKey)) {
+            return reject("envelope key does not match data's declared primary_key fields");
+        }
+    }
+    catch (err) {
+        if (err instanceof RecordKeyError)
+            return reject(err.message);
+        throw err;
+    }
+    // Before the equality check, so the outcome depends only on the data and
+    // the declared schema, never on what happens to be stored already.
+    const violation = validateData?.(envelope.stream, envelope.instance, data);
+    if (violation)
+        return reject(violation);
+    if (existing && !existing.deleted) {
+        if (canonicalJson(existing.data) === canonicalJson(data)) {
+            return unchanged();
+        }
+        // Core: append_only records are immutable and duplicate keys are
+        // idempotent, so the first write stands. The flag lets the producer
+        // count a source that changed a record it declared immutable.
+        if (semantics === "append_only")
+            return unchanged("append_only_conflict");
+    }
+    return {
+        outcome: { index, outcome: "accepted" },
+        write: { recordKey, data },
+    };
+}
+/** JSON with object keys sorted at every depth. */
+export function canonicalJson(value) {
+    return JSON.stringify(sortKeys(value));
+}
+function sortKeys(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    if (value !== null && typeof value === "object") {
+        return Object.fromEntries(Object.keys(value)
+            .sort()
+            .map((key) => [key, sortKeys(value[key])]));
+    }
+    return value;
+}
+/** The per-index outcomes plus the counts callers already read. */
+export function summarizeIngest(results) {
+    let accepted = 0;
+    let unchanged = 0;
+    const rejected = [];
+    for (const result of results) {
+        if (result.outcome === "accepted")
+            accepted += 1;
+        else if (result.outcome === "unchanged")
+            unchanged += 1;
+        else
+            rejected.push({ index: result.index, reason: result.reason });
+    }
+    return { accepted, unchanged, rejected, results };
+}
+//# sourceMappingURL=ingest-plan.js.map

package/dist/storage/pdpp-records/ingest-plan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingest-plan.js","sourceRoot":"","sources":["../../../src/storage/pdpp-records/ingest-plan.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,cAAc,EACd,cAAc,GACf,MAAM,iBAAiB,CAAC;AAwCzB,MAAM,UAAU,UAAU,CACxB,KAAa,EACb,QAAiC,EACjC,SAA0B,EAC1B,UAAoB,EACpB,OAA0D,EAC1D,YAAkC;IAElC,MAAM,MAAM,GAAG,CAAC,MAAc,EAAc,EAAE,CAAC,CAAC;QAC9C,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE;KAChD,CAAC,CAAC;IACH,MAAM,SAAS,GAAG,CAAC,IAA6B,EAAc,EAAE,CAAC,CAAC;QAChE,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,GAAG,CAAC,IAAI,IAAI,EAAE,IAAI,EAAE,CAAC,EAAE;KAChE,CAAC,CAAC;IAEH,IAAI,OAAO,QAAQ,CAAC,UAAU,KAAK,QAAQ,IAAI,CAAC,QAAQ,CAAC,UAAU,EAAE,CAAC;QACpE,OAAO,MAAM,CAAC,uCAAuC,CAAC,CAAC;IACzD,CAAC;IACD,sEAAsE;IACtE,uEAAuE;IACvE,IACE,QAAQ,CAAC,EAAE,IAAI,IAAI;QACnB,QAAQ,CAAC,EAAE,KAAK,QAAQ;QACxB,QAAQ,CAAC,EAAE,KAAK,QAAQ,EACxB,CAAC;QACD,OAAO,MAAM,CAAC,iCAAiC,CAAC,CAAC;IACnD,CAAC;IAED,IAAI,SAAiB,CAAC;IACtB,IAAI,CAAC;QACH,SAAS,GAAG,eAAe,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;IAC5C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,cAAc;YAAE,OAAO,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAC9D,MAAM,GAAG,CAAC;IACZ,CAAC;IACD,MAAM,QAAQ,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IAEpC,IAAI,QAAQ,CAAC,EAAE,KAAK,QAAQ,EAAE,CAAC;QAC7B,IAAI,SAAS,KAAK,aAAa,EAAE,CAAC;YAChC,OAAO,MAAM,CAAC,sDAAsD,CAAC,CAAC;QACxE,CAAC;QACD,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,OAAO;YAAE,OAAO,SAAS,EAAE,CAAC;QACtD,OAAO;YACL,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE;YACvC,KAAK,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE;SACjC,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC;IAC3B,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACrE,OAAO,MAAM,CAAC,uCAAuC,CAAC,CAAC;IACzD,CAAC;IACD,IAAI,CAAC;QACH,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,GAAG,EAAE,IAAI,EAAE,UAAU,CAAC,EAAE,CAAC;YACpD,OAAO,MAAM,CACX,gEAAgE,CACjE,CAAC;QACJ,CAAC;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,cAAc;YAAE,OAAO,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAC9D,MAAM,GAAG,CAAC;IACZ,CAAC;IACD,yEAAyE;IACzE,mEAAmE;IACnE,MAAM,SAAS,GAAG,YAAY,EAAE,CAAC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IAC3E,IAAI,SAAS;QAAE,OAAO,MAAM,CAAC,SAAS,CAAC,CAAC;IAExC,IAAI,QAAQ,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;QAClC,IAAI,aAAa,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,aAAa,CAAC,IAAI,CAAC,EAAE,CAAC;YACzD,OAAO,SAAS,EAAE,CAAC;QACrB,CAAC;QACD,iEAAiE;QACjE,oEAAoE;QACpE,8DAA8D;QAC9D,IAAI,SAAS,KAAK,aAAa;YAAE,OAAO,SAAS,CAAC,sBAAsB,CAAC,CAAC;IAC5E,CAAC;IACD,OAAO;QACL,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE;QACvC,KAAK,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE;KAC3B,CAAC;AACJ,CAAC;AAED,mDAAmD;AACnD,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,OAAO,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;AACzC,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACrD,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,IAAI,CAAC,KAAgC,CAAC;aAC1C,IAAI,EAAE;aACN,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,QAAQ,CAAE,KAAiC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAC1E,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,eAAe,CAAC,OAAwB;IACtD,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,MAAM,QAAQ,GAA6B,EAAE,CAAC;IAC9C,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,MAAM,CAAC,OAAO,KAAK,UAAU;YAAE,QAAQ,IAAI,CAAC,CAAC;aAC5C,IAAI,MAAM,CAAC,OAAO,KAAK,WAAW;YAAE,SAAS,IAAI,CAAC,CAAC;;YACnD,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IACrE,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;AACpD,CAAC"}