@kubun/connector 0.17.2 → 0.18.0

package/lib/index.d.ts

@@ -3,4 +3,9 @@ export { clusterModelURNs, resolveModelID } from './cluster-utils.js';
 export { ConnectorError, type ConnectorErrorKind, type ConnectorErrorOptions, classifyHTTPStatus, connectorHTTPError, markWriteSent, } from './errors.js';
 export { connectorClusters, connectorModelIDs } from './models/cluster.js';
 export { externalEntityDefinition } from './models/external-entity.js';
-export type { ActionDefinition, ActionHandler, ActionHandlerFactory, ActionResult, ActionTargetResolver, ActionTargetStorage, ActionWriteContext, ActionWriteResult, ClientDataProvider, ClientProviderFactory, ConnectorAuth, ConnectorDefinition, ConnectorSyncEventPayload, CreatedSourceIDPredictor, DataProvider, DeadLetter, DeviceConnectorAuth, DevicePermission, EntityBatch, EntityRecord, FetchChangesParams, FetchedAbsentEntity, FetchedEntity, FetchedPresentEntity, FetchParams, IntentCanonicalizer, IntentComparison, JSONValue, LocalAnnotationMerger, OAuthConnectorAuth, OAuthState, PendingOp, ReconcileResult, Recovery, ResolvedActionTarget, ServerDataProvider, ServerProviderFactory, SyncBoundary, SyncCompleteEvent, SyncErrorEvent, SyncEvent, SyncFailureSample, SyncProgressCASCurrent, SyncProgressCASResult, SyncProgressEvent, SyncProgressRecompute, SyncState, SyncStateEntry, SyncStateStore, SyncStatus, UserSyncPreferences, WebhookParams, WebhookRegistration, WriteAttachment, } from './types.js';
+export { type ObservationDelegatedWrite, type ObservationDeps, observationRecordType, parseObservationPayload, providerValueDigest, } from './observation.js';
+export { MAX_OBSERVATION_CAPABILITIES, MAX_OBSERVATION_CAPABILITY_BYTES, MAX_OBSERVATION_CAPABILITY_DEPTH, MAX_OBSERVATION_CAPABILITY_TOKEN_BYTES, MAX_OBSERVATION_CAPABILITY_VISITS, MAX_OBSERVATION_JWT_BYTES, MAX_OBSERVATION_PREFETCH_DIDS, ObservationCapabilityError, type ObservationCapabilityValidationParams, signObservationOp, validateObservationCapabilities, } from './observation-capabilities.js';
+export { addBoundaryDuration, type FetchOrAbsentOptions, fetchOrAbsent, isNotFoundError, parseMaxAgeDays, parseSyncBoundaryDuration, type TargetedRead, } from './provider-utils.js';
+export { classifyVerification, isSweepCandidate, type RelistReceipt, type SweepCandidateReceipt, type VerificationOutcome, type VerificationResult, } from './sweep.js';
+export { carryField, isFieldTrimmed, refuseCutLists, type TrimmedArray, type TrimmedField, TrimmedFieldWriteError, type TrimmedString, } from './trim.js';
+export type { ActionDefinition, ActionHandler, ActionHandlerFactory, ActionResult, ActionTargetResolver, ActionTargetStorage, ActionWriteContext, ActionWriteResult, ClientDataProvider, ClientProviderFactory, ConnectorAuth, ConnectorDefinition, ConnectorSyncEventPayload, CreatedSourceIDPredictor, DataProvider, DeadLetter, DeviceConnectorAuth, DevicePermission, EntityBatch, EntityRecord, FetchChangesParams, FetchedAbsentEntity, FetchedEntity, FetchedPresentEntity, FetchParams, IntentCanonicalizer, IntentComparison, JSONValue, LocalAnnotationMerger, OAuthConnectorAuth, OAuthState, Observation, PendingOp, ReconcileResult, Recovery, ResolvedActionTarget, ServerDataProvider, ServerProviderFactory, SyncBoundary, SyncCompleteEvent, SyncErrorEvent, SyncEvent, SyncFailureSample, SyncProgressCASCurrent, SyncProgressCASResult, SyncProgressEvent, SyncProgressRecompute, SyncState, SyncStateEntry, SyncStateStore, SyncStatus, SyncSweep, UserSyncPreferences, WebhookParams, WebhookRegistration, WriteAttachment, } from './types.js';

package/lib/index.js

@@ -3,3 +3,8 @@ export { clusterModelURNs, resolveModelID } from './cluster-utils.js';
 export { ConnectorError, classifyHTTPStatus, connectorHTTPError, markWriteSent } from './errors.js';
 export { connectorClusters, connectorModelIDs } from './models/cluster.js';
 export { externalEntityDefinition } from './models/external-entity.js';
+export { observationRecordType, parseObservationPayload, providerValueDigest } from './observation.js';
+export { MAX_OBSERVATION_CAPABILITIES, MAX_OBSERVATION_CAPABILITY_BYTES, MAX_OBSERVATION_CAPABILITY_DEPTH, MAX_OBSERVATION_CAPABILITY_TOKEN_BYTES, MAX_OBSERVATION_CAPABILITY_VISITS, MAX_OBSERVATION_JWT_BYTES, MAX_OBSERVATION_PREFETCH_DIDS, ObservationCapabilityError, signObservationOp, validateObservationCapabilities } from './observation-capabilities.js';
+export { addBoundaryDuration, fetchOrAbsent, isNotFoundError, parseMaxAgeDays, parseSyncBoundaryDuration } from './provider-utils.js';
+export { classifyVerification, isSweepCandidate } from './sweep.js';
+export { carryField, isFieldTrimmed, refuseCutLists, TrimmedFieldWriteError } from './trim.js';

package/lib/observation-capabilities.d.ts

@@ -0,0 +1,28 @@
+import type { SigningIdentity } from '@kokuin/token';
+import { type RecordClaim, RecordContentRefusalError } from '@kubun/records';
+export declare const MAX_OBSERVATION_CAPABILITIES = 16;
+export declare const MAX_OBSERVATION_CAPABILITY_BYTES: number;
+export declare const MAX_OBSERVATION_CAPABILITY_DEPTH = 5;
+export declare const MAX_OBSERVATION_CAPABILITY_VISITS = 64;
+export declare const MAX_OBSERVATION_PREFETCH_DIDS = 64;
+export declare const MAX_OBSERVATION_CAPABILITY_TOKEN_BYTES: number;
+export declare const MAX_OBSERVATION_JWT_BYTES: number;
+export declare class ObservationCapabilityError extends RecordContentRefusalError {
+    constructor(message: string, options?: ErrorOptions);
+}
+type ObservationCapabilities = {
+    cap: unknown;
+    issuer: string;
+    owner: string;
+};
+export type ObservationCapabilityValidationParams = ObservationCapabilities | {
+    opJWT: string;
+};
+/** Bound all traversal work before any signer or capability is resolved or verified. */
+export declare function validateObservationCapabilities(params: ObservationCapabilityValidationParams): Array<string>;
+type SignedObservationOp = {
+    opJWT: string;
+    opHash: string;
+};
+export declare function signObservationOp(identity: SigningIdentity, claim: RecordClaim): Promise<SignedObservationOp>;
+export {};

package/lib/observation-capabilities.js

@@ -0,0 +1,115 @@
+import { RecordContentRefusalError, signRecordOp } from '@kubun/records';
+import { fromB64U, fromUTF, toUTF } from '@sozai/codec';
+export const MAX_OBSERVATION_CAPABILITIES = 16;
+export const MAX_OBSERVATION_CAPABILITY_BYTES = 64 * 1024;
+export const MAX_OBSERVATION_CAPABILITY_DEPTH = 5;
+export const MAX_OBSERVATION_CAPABILITY_VISITS = 64;
+export const MAX_OBSERVATION_PREFETCH_DIDS = 64;
+// Cheap per-string guard before any decode.
+export const MAX_OBSERVATION_CAPABILITY_TOKEN_BYTES = 64 * 1024;
+export const MAX_OBSERVATION_JWT_BYTES = 256 * 1024;
+export class ObservationCapabilityError extends RecordContentRefusalError {
+    constructor(message, options){
+        super(message);
+        this.name = 'ObservationCapabilityError';
+        this.cause = options?.cause;
+    }
+}
+function isObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function byteLength(value, limit) {
+    if (value.length > limit) throw new ObservationCapabilityError('Observation JWT byte limit exceeded');
+    const bytes = fromUTF(value).byteLength;
+    if (bytes > limit) throw new ObservationCapabilityError('Observation JWT byte limit exceeded');
+    return bytes;
+}
+function tokenPayload(token) {
+    const parts = token.split('.');
+    if (parts.length !== 3 || parts[1] === undefined) throw new ObservationCapabilityError('Observation capability JWT is malformed');
+    let value;
+    try {
+        value = JSON.parse(toUTF(fromB64U(parts[1])));
+    } catch (cause) {
+        throw new ObservationCapabilityError('Observation capability JWT is malformed', {
+            cause
+        });
+    }
+    if (!isObject(value)) throw new ObservationCapabilityError('Observation capability payload is malformed');
+    return value;
+}
+function observationCapabilities(opJWT) {
+    byteLength(opJWT, MAX_OBSERVATION_JWT_BYTES);
+    const payload = tokenPayload(opJWT);
+    if (typeof payload.iss !== 'string' || typeof payload.claim !== 'string') throw new ObservationCapabilityError('Observation claim envelope is malformed');
+    let claim;
+    try {
+        claim = JSON.parse(toUTF(fromB64U(payload.claim)));
+    } catch (cause) {
+        throw new ObservationCapabilityError('Observation claim is malformed', {
+            cause
+        });
+    }
+    if (!isObject(claim) || typeof claim.owner !== 'string' || !isObject(claim.meta)) throw new ObservationCapabilityError('Observation claim is malformed');
+    return {
+        cap: claim.meta.cap,
+        issuer: payload.iss,
+        owner: claim.owner
+    };
+}
+function tokensOf(cap) {
+    if (cap == null) return [];
+    if (typeof cap === 'string') return [
+        cap
+    ];
+    if (Array.isArray(cap)) return cap;
+    throw new ObservationCapabilityError('Observation capabilities are malformed');
+}
+/** Bound all traversal work before any signer or capability is resolved or verified. */ export function validateObservationCapabilities(params) {
+    const { cap, issuer, owner } = 'opJWT' in params ? observationCapabilities(params.opJWT) : params;
+    const roots = tokensOf(cap);
+    if (roots.length > MAX_OBSERVATION_CAPABILITIES) throw new ObservationCapabilityError('Observation capability count limit exceeded');
+    const dids = new Set();
+    const addDID = (did)=>{
+        dids.add(did);
+        if (dids.size > MAX_OBSERVATION_PREFETCH_DIDS) throw new ObservationCapabilityError('Observation prefetch DID limit exceeded');
+    };
+    addDID(owner);
+    addDID(issuer);
+    let visits = 0;
+    let bytes = 0;
+    const visit = (token, depth)=>{
+        if (depth > MAX_OBSERVATION_CAPABILITY_DEPTH) throw new ObservationCapabilityError('Observation capability depth limit exceeded');
+        if (++visits > MAX_OBSERVATION_CAPABILITY_VISITS) throw new ObservationCapabilityError('Observation capability visit limit exceeded');
+        if (typeof token !== 'string' || token.length === 0) throw new ObservationCapabilityError('Observation capability token is malformed');
+        bytes += byteLength(token, MAX_OBSERVATION_CAPABILITY_TOKEN_BYTES);
+        if (bytes > MAX_OBSERVATION_CAPABILITY_BYTES) throw new ObservationCapabilityError('Observation aggregate capability byte limit exceeded');
+        const payload = tokenPayload(token);
+        for (const field of [
+            'iss',
+            'sub',
+            'aud'
+        ]){
+            const did = payload[field];
+            if (typeof did === 'string') addDID(did);
+        }
+        // Embedded and repeated tokens spend the budget on every visit.
+        for (const nested of tokensOf(payload.cap))visit(nested, depth + 1);
+    };
+    for (const token of roots)visit(token, 0);
+    return [
+        ...dids
+    ];
+}
+export async function signObservationOp(identity, claim) {
+    validateObservationCapabilities({
+        cap: claim.meta.cap,
+        issuer: identity.id,
+        owner: claim.owner
+    });
+    const signed = await signRecordOp(identity, claim);
+    validateObservationCapabilities({
+        opJWT: signed.opJWT
+    });
+    return signed;
+}

package/lib/observation.d.ts

@@ -0,0 +1,18 @@
+import { type RecordStoreAdapter, type RecordTypeDefinition } from '@kubun/records';
+import type { Observation } from './types.js';
+export type ObservationDeps = {
+    resolveController: (did: string) => Promise<string | null>;
+    verifyDelegatedWrite?: (params: ObservationDelegatedWrite) => Promise<boolean>;
+    now?: () => number;
+};
+export type ObservationDelegatedWrite = {
+    documentID: string;
+    owner: string;
+    issuer: string;
+    tokens: Array<string>;
+    atTime: number;
+    store: RecordStoreAdapter;
+};
+export declare function providerValueDigest(value: unknown, fields: ReadonlyArray<string>): string;
+export declare function parseObservationPayload(payload: Uint8Array | null): Observation | null;
+export declare function observationRecordType(deps: ObservationDeps): RecordTypeDefinition;

package/lib/observation.js

@@ -0,0 +1,121 @@
+import { HLC } from '@kubun/hlc';
+import { digestJSON } from '@kubun/id';
+import { recordPayloadMatches } from '@kubun/records';
+import { toB64U, toUTF } from '@sozai/codec';
+import { ObservationCapabilityError, validateObservationCapabilities } from './observation-capabilities.js';
+function isObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function withoutObjectNulls(value) {
+    if (Array.isArray(value)) return value.map((item)=>withoutObjectNulls(item));
+    if (!isObject(value)) return value;
+    const result = {};
+    for (const [key, item] of Object.entries(value)){
+        if (item !== null && item !== undefined) result[key] = withoutObjectNulls(item);
+    }
+    return result;
+}
+export function providerValueDigest(value, fields) {
+    const source = isObject(value) ? value : {};
+    const projection = {};
+    for (const field of fields){
+        const item = source[field];
+        if (item !== null && item !== undefined) projection[field] = withoutObjectNulls(item);
+    }
+    return toB64U(digestJSON(projection));
+}
+export function parseObservationPayload(payload) {
+    if (payload === null) return null;
+    let value;
+    try {
+        value = JSON.parse(toUTF(payload));
+    } catch  {
+        return null;
+    }
+    if (!isObject(value)) return null;
+    const { documentID, fetchHLC, decisionHLC, present, valueDigest } = value;
+    if (Object.keys(value).length !== 5 || typeof documentID !== 'string' || typeof fetchHLC !== 'string' || typeof decisionHLC !== 'string' || typeof present !== 'boolean' || (present ? typeof valueDigest !== 'string' : valueDigest !== null)) return null;
+    const fetch = HLC.tryParse(fetchHLC);
+    const decision = HLC.tryParse(decisionHLC);
+    if (fetch === null || decision === null || HLC.serialize(fetch) !== fetchHLC || HLC.serialize(decision) !== decisionHLC || decisionHLC !== fetchHLC) return null;
+    return {
+        documentID,
+        fetchHLC,
+        decisionHLC,
+        present,
+        valueDigest: valueDigest
+    };
+}
+export function observationRecordType(deps) {
+    return {
+        type: 'connector.observation',
+        policy: {
+            kind: 'monotonic',
+            versionOrder: 'hlc',
+            version: (claim)=>{
+                const version = claim.meta.version;
+                const parsed = typeof version === 'string' ? HLC.tryParse(version) : null;
+                return parsed === null ? [
+                    Number.NaN
+                ] : [
+                    parsed.wallTime,
+                    parsed.counter
+                ];
+            }
+        },
+        dependsOn: [],
+        dependencies: ()=>[],
+        lockKeys: async (record)=>[
+                {
+                    type: 'connector.observation',
+                    key: JSON.stringify([
+                        record.owner,
+                        record.id
+                    ])
+                }
+            ],
+        precheck: async (op, record)=>{
+            try {
+                validateObservationCapabilities({
+                    opJWT: record.opJWT
+                });
+            } catch (error) {
+                if (error instanceof ObservationCapabilityError) return false;
+                throw error;
+            }
+            if (op.claim.deleted) return record.payload === null;
+            const observation = parseObservationPayload(record.payload);
+            return observation !== null && recordPayloadMatches(record, op.claim) && observation.documentID === op.claim.id && observation.decisionHLC === op.claim.meta.version && op.claim.hlc === op.claim.meta.version;
+        },
+        authorize: async (op, ctx)=>{
+            try {
+                validateObservationCapabilities({
+                    cap: op.claim.meta.cap,
+                    issuer: op.issuer,
+                    owner: op.claim.owner
+                });
+            } catch (error) {
+                if (error instanceof ObservationCapabilityError) return false;
+                throw error;
+            }
+            if (op.claim.hlc !== op.claim.meta.version) return false;
+            const adapter = ctx.store.adapterForType?.('connector.observation') ?? ctx.store;
+            if (adapter.getObservationDocumentOwner === undefined) throw new Error('Observation adapter cannot resolve document owner');
+            const documentOwner = await adapter.getObservationDocumentOwner(op.claim.id);
+            if (documentOwner === null || documentOwner !== op.claim.owner) return false;
+            if (op.issuer === op.claim.owner) return true;
+            if (await deps.resolveController(op.issuer) === op.claim.owner) return true;
+            const cap = op.claim.meta.cap;
+            if (!Array.isArray(cap) || cap.length === 0 || !cap.every((token)=>typeof token === 'string') || deps.verifyDelegatedWrite === undefined) return false;
+            if (HLC.tryParse(op.claim.hlc) === null) return false;
+            return await deps.verifyDelegatedWrite({
+                documentID: op.claim.id,
+                owner: op.claim.owner,
+                issuer: op.issuer,
+                tokens: cap,
+                atTime: Math.floor((deps.now ?? Date.now)() / 1000),
+                store: adapter
+            });
+        }
+    };
+}

package/lib/provider-utils.d.ts

@@ -0,0 +1,22 @@
+import type { EntityRecord, ReconcileResult, SyncBoundary } from './types.js';
+export type TargetedRead = {
+    record: EntityRecord;
+    providerETag?: string;
+};
+export type FetchOrAbsentOptions = {
+    sourceID: string;
+    sourceFetchHLC: string;
+    read: () => Promise<TargetedRead>;
+};
+export declare function isNotFoundError(err: unknown): boolean;
+export declare function fetchOrAbsent(options: FetchOrAbsentOptions): Promise<ReconcileResult>;
+export declare function parseMaxAgeDays(boundary: SyncBoundary | undefined): number | null;
+export declare function parseSyncBoundaryDuration(boundary: SyncBoundary | undefined): number | null;
+/**
+ * `from` moved forward by a `P<n>D` or `P<n>Y` duration, in UTC. Years are
+ * calendar years (a year spanning a leap day is 366 days); a leap day plus a
+ * whole number of years lands on the last day of February when the target year
+ * has none. Case-insensitive, like `parseMaxAgeDays`. Returns null for any
+ * other or non-positive duration, and for one past the representable dates.
+ */
+export declare function addBoundaryDuration(from: Date, duration: string): Date | null;

package/lib/provider-utils.js

@@ -0,0 +1,62 @@
+import { parseCatalogDuration } from '@kubun/protocol';
+export function isNotFoundError(err) {
+    return err?.httpStatus === 404;
+}
+export async function fetchOrAbsent(options) {
+    try {
+        const { record, providerETag } = await options.read();
+        return {
+            present: true,
+            record,
+            sourceFetchHLC: options.sourceFetchHLC,
+            ...providerETag != null ? {
+                providerETag
+            } : {}
+        };
+    } catch (err) {
+        if (isNotFoundError(err)) {
+            return {
+                present: false,
+                sourceID: options.sourceID,
+                sourceFetchHLC: options.sourceFetchHLC
+            };
+        }
+        throw err;
+    }
+}
+export function parseMaxAgeDays(boundary) {
+    if (boundary?.maxAge == null) return null;
+    try {
+        return parseCatalogDuration(boundary.maxAge.toUpperCase()) / 86_400_000;
+    } catch  {
+        return null;
+    }
+}
+export function parseSyncBoundaryDuration(boundary) {
+    return boundary?.maxAge == null ? null : parseCatalogDuration(boundary.maxAge);
+}
+const BOUNDARY_DURATION = /^P(\d+)([DY])$/i;
+/**
+ * `from` moved forward by a `P<n>D` or `P<n>Y` duration, in UTC. Years are
+ * calendar years (a year spanning a leap day is 366 days); a leap day plus a
+ * whole number of years lands on the last day of February when the target year
+ * has none. Case-insensitive, like `parseMaxAgeDays`. Returns null for any
+ * other or non-positive duration, and for one past the representable dates.
+ */ export function addBoundaryDuration(from, duration) {
+    const match = BOUNDARY_DURATION.exec(duration);
+    if (match?.[1] == null) return null;
+    const amount = Number.parseInt(match[1], 10);
+    if (amount <= 0) return null;
+    const result = new Date(from.getTime());
+    if (match[2]?.toUpperCase() === 'D') {
+        result.setUTCDate(result.getUTCDate() + amount);
+    } else {
+        const month = result.getUTCMonth();
+        result.setUTCFullYear(result.getUTCFullYear() + amount);
+        if (result.getUTCMonth() !== month) {
+            // Day 0 of the overflowed month is the last day of the intended one.
+            result.setUTCDate(0);
+        }
+    }
+    return Number.isNaN(result.getTime()) ? null : result;
+}

package/lib/sweep.d.ts

@@ -0,0 +1,15 @@
+import type { FetchedEntity, SyncSweep } from './types.js';
+export type RelistReceipt = SyncSweep;
+export type VerificationOutcome = 'present' | 'absent' | 'cancelled' | 'uncertain';
+export type VerificationResult = FetchedEntity | {
+    outcome: 'cancelled' | 'uncertain';
+    sourceFetchHLC: string;
+};
+export declare function classifyVerification(result: VerificationResult | unknown): VerificationOutcome;
+export type SweepCandidateReceipt = Pick<RelistReceipt, 'complete' | 'predicate'>;
+/**
+ * Whether a stored document is a deletion candidate of a completed relist:
+ * not listed (`keep`) and inside the receipt's predicate. The stored start
+ * date is a conservative subset of Calendar's list window.
+ */
+export declare function isSweepCandidate(receipt: SweepCandidateReceipt, keep: ReadonlySet<string>, data: Record<string, unknown>): boolean;

package/lib/sweep.js

@@ -0,0 +1,22 @@
+export function classifyVerification(result) {
+    if (result == null || typeof result !== 'object') return 'uncertain';
+    if ('outcome' in result) {
+        return result.outcome === 'cancelled' ? 'cancelled' : 'uncertain';
+    }
+    if ('present' in result) return result.present === true ? 'present' : result.present === false ? 'absent' : 'uncertain';
+    return 'uncertain';
+}
+/**
+ * Whether a stored document is a deletion candidate of a completed relist:
+ * not listed (`keep`) and inside the receipt's predicate. The stored start
+ * date is a conservative subset of Calendar's list window.
+ */ export function isSweepCandidate(receipt, keep, data) {
+    if (!receipt.complete || receipt.predicate == null) return false;
+    if (typeof data.sourceID !== 'string' || keep.has(data.sourceID)) return false;
+    const timestamp = data[receipt.predicate.field];
+    if (typeof timestamp !== 'string') return false;
+    const value = Date.parse(timestamp);
+    const from = receipt.predicate.from == null ? Number.NEGATIVE_INFINITY : Date.parse(receipt.predicate.from);
+    const to = receipt.predicate.to == null ? Number.POSITIVE_INFINITY : Date.parse(receipt.predicate.to);
+    return Number.isFinite(value) && value >= from && value < to;
+}

package/lib/trim.d.ts

@@ -0,0 +1,59 @@
+import { ConnectorError } from './errors.js';
+import type { ActionWriteContext } from './types.js';
+/** A source string cut to its model's `maxLength`, in code points. */
+export type TrimmedString = {
+    /** JSON Pointer (RFC 6901) to the value in the written document. */
+    path: string;
+    kind: 'string';
+    /** The source value's length in code points, before the cut. */
+    originalLength: number;
+};
+/** A source array cut to its model's `maxItems`. */
+export type TrimmedArray = {
+    /** JSON Pointer (RFC 6901) to the value in the written document. */
+    path: string;
+    kind: 'array';
+    /** The source array's item count, before the cut. */
+    originalCount: number;
+};
+/**
+ * A source value a connector fitted to its model's caps before writing the
+ * document: the stored value is a prefix of the provider's, never the whole.
+ */
+export type TrimmedField = TrimmedString | TrimmedArray;
+/**
+ * Whether the stored value of top-level `field` is not the provider's own:
+ * the field itself, or any value inside it, was trimmed.
+ */
+export declare function isFieldTrimmed(trimmedFields: ReadonlyArray<TrimmedField> | undefined, field: string): boolean;
+/**
+ * Refuses a write whose caller-set fields land on a list that was cut to the
+ * model's cap, at the field or anywhere below it. The caller built that value
+ * from the stored prefix, never the provider's full list, so sending it would
+ * delete the items the cut dropped. A caller-set string on a cut string path
+ * is still written: the caller set that whole value.
+ */
+export declare function refuseCutLists(params: Record<string, unknown>, context: ActionWriteContext | undefined): void;
+/**
+ * A write would send a field whose stored value was trimmed, so it would cut
+ * the provider's full value down to the stored prefix. Classified as a
+ * definite rejection: nothing was sent, and the same write is refused again.
+ */
+export declare class TrimmedFieldWriteError extends ConnectorError {
+    #private;
+    /**
+     * `list` names a write of a cut list, which the caller cannot make whole:
+     * it never saw the items the cut dropped.
+     */
+    constructor(field: string, options?: {
+        list?: boolean;
+    });
+    get field(): string;
+}
+/**
+ * The target document's value of `field`, for a write that must resend it
+ * alongside the fields it changes (a provider that takes two fields only as a
+ * pair, say). Throws {@link TrimmedFieldWriteError} when the stored value was
+ * trimmed, rather than write the prefix over the provider's full value.
+ */
+export declare function carryField(existing: Record<string, unknown> | undefined, field: string, context: ActionWriteContext | undefined): unknown;

package/lib/trim.js

@@ -0,0 +1,64 @@
+import { ConnectorError } from './errors.js';
+function pointerSegment(field) {
+    return field.replaceAll('~', '~0').replaceAll('/', '~1');
+}
+function isAtOrBelow(path, field) {
+    const pointer = `/${pointerSegment(field)}`;
+    return path === pointer || path.startsWith(`${pointer}/`);
+}
+/**
+ * Whether the stored value of top-level `field` is not the provider's own:
+ * the field itself, or any value inside it, was trimmed.
+ */ export function isFieldTrimmed(trimmedFields, field) {
+    if (trimmedFields == null) return false;
+    return trimmedFields.some((trimmed)=>isAtOrBelow(trimmed.path, field));
+}
+/**
+ * Refuses a write whose caller-set fields land on a list that was cut to the
+ * model's cap, at the field or anywhere below it. The caller built that value
+ * from the stored prefix, never the provider's full list, so sending it would
+ * delete the items the cut dropped. A caller-set string on a cut string path
+ * is still written: the caller set that whole value.
+ */ export function refuseCutLists(params, context) {
+    const cutLists = context?.trimmedFields?.filter((trimmed)=>trimmed.kind === 'array') ?? [];
+    if (cutLists.length === 0) return;
+    for (const field of Object.keys(params)){
+        if (cutLists.some((trimmed)=>isAtOrBelow(trimmed.path, field))) {
+            throw new TrimmedFieldWriteError(field, {
+                list: true
+            });
+        }
+    }
+}
+/**
+ * A write would send a field whose stored value was trimmed, so it would cut
+ * the provider's full value down to the stored prefix. Classified as a
+ * definite rejection: nothing was sent, and the same write is refused again.
+ */ export class TrimmedFieldWriteError extends ConnectorError {
+    #field;
+    /**
+   * `list` names a write of a cut list, which the caller cannot make whole:
+   * it never saw the items the cut dropped.
+   */ constructor(field, options = {}){
+        super(options.list === true ? `"${field}" holds a cut copy of the provider's list; writing it would drop the items the cut left out` : `"${field}" holds a trimmed copy of the provider's value; set it explicitly to write it`, {
+            code: 'TRIMMED_FIELD',
+            kind: 'rejected'
+        });
+        this.name = 'TrimmedFieldWriteError';
+        this.#field = field;
+    }
+    get field() {
+        return this.#field;
+    }
+}
+/**
+ * The target document's value of `field`, for a write that must resend it
+ * alongside the fields it changes (a provider that takes two fields only as a
+ * pair, say). Throws {@link TrimmedFieldWriteError} when the stored value was
+ * trimmed, rather than write the prefix over the provider's full value.
+ */ export function carryField(existing, field, context) {
+    if (isFieldTrimmed(context?.trimmedFields, field)) {
+        throw new TrimmedFieldWriteError(field);
+    }
+    return existing?.[field];
+}

package/lib/types.d.ts

@@ -1,6 +1,15 @@
 import type { Credential, ProviderAccount } from '@kubun/credential-types';
 import type { ClustersRecord } from '@kubun/protocol';
 import type { JSONSchema } from 'json-schema-typed';
+import type { VerificationResult } from './sweep.js';
+import type { TrimmedField } from './trim.js';
+export type Observation = {
+    documentID: string;
+    fetchHLC: string;
+    decisionHLC: string;
+    present: boolean;
+    valueDigest: string | null;
+};
 export type OAuthState = {
     provider: string;
     redirectURL: string;
@@ -82,6 +91,7 @@ export type SyncBoundary = {
     maxAge?: string;
     since?: string;
     maxEntities?: number;
+    maxAhead?: string;
 };
 export type UserSyncPreferences = {
     connectorName: string;
@@ -108,10 +118,41 @@ export type FetchedPresentEntity = Extract<FetchedEntity, {
 export type FetchedAbsentEntity = Extract<FetchedEntity, {
     present: false;
 }>;
+/**
+ * A completed provider relist receipt for one source partition, emitted on the
+ * partition's final page only.
+ *
+ * - `relist`: `keep` lists every source ID the listing returned; documents in
+ *   the partition whose stored `predicate.field` lies in `[from, to)` and are
+ *   not kept become durable candidates, each deleted only after a by-ID
+ *   verification reports it absent or cancelled.
+ * - `partition-removal`: the provider reported the whole partition gone (such
+ *   as a removed calendar); `predicate` is null, `keep` is unused, and every
+ *   document in it is removed with `sourceFetchHLC`, without per-document
+ *   verification.
+ */
+export type SyncSweep = {
+    modelID: string;
+    scope: Record<string, string>;
+    keep: Array<string>;
+    sourceFetchHLC: string;
+    partition: string;
+    /** The listing's token or snapshot provenance; keys the sweep checkpoint. */
+    provenance: string;
+    complete: boolean;
+    /** The exact relist window as ISO bounds; documents outside it are untouched. */
+    predicate: {
+        field: string;
+        from: string | null;
+        to: string | null;
+    } | null;
+    kind: 'relist' | 'partition-removal';
+};
 export type EntityBatch = {
     modelID: string;
     entities: Array<FetchedPresentEntity>;
     deleted?: Array<FetchedAbsentEntity>;
+    sweep?: SyncSweep;
     checkpoint?: unknown;
     hasMore: boolean;
 };
@@ -146,6 +187,7 @@ export type DataProvider = {
     fetchAll(params: FetchParams): AsyncIterable<EntityBatch>;
     fetchChanges(params: FetchChangesParams): AsyncIterable<EntityBatch>;
     fetchEntity(model: string, sourceID: string, snapshot: unknown): Promise<FetchedEntity>;
+    verifyEntity?(model: string, sourceID: string, snapshot: unknown): Promise<VerificationResult>;
     reconcile(model: string, sourceID: string, snapshot: unknown): Promise<ReconcileResult>;
     supportedStrategies: Array<'polling' | 'on-demand'>;
 };
@@ -234,6 +276,14 @@ export type ActionWriteContext = {
      * the write instead of being overwritten. Absent when unknown.
      */
     providerETag?: string | null;
+    /**
+     * The target document's values that were trimmed to the model's caps when
+     * it was synced (see `TrimmedField`). A write that sends a field the caller
+     * did not set — one carried from the target document — refuses a trimmed
+     * one (`carryField`) rather than cut the provider's value to the stored
+     * prefix. Absent or empty when nothing was trimmed.
+     */
+    trimmedFields?: ReadonlyArray<TrimmedField>;
 };
 export type ActionHandler = {
     create(model: string, params: Record<string, unknown>, context?: ActionWriteContext): Promise<ActionWriteResult>;
@@ -393,8 +443,12 @@ export type SyncErrorEvent = {
 };
 export type SyncEvent = SyncProgressEvent | SyncCompleteEvent | SyncErrorEvent;
 export type ConnectorSyncEventPayload = {
-    type: 'started' | 'progress' | 'completed' | 'error';
+    type: 'started' | 'progress' | 'completed' | 'error' | 'entity:trimmed';
     connectorName: string;
+    modelID?: string;
+    documentID?: string;
+    sourceID?: string;
+    trimmedFields?: Array<TrimmedField>;
     entitiesProcessed?: number;
     entitiesFailed?: number;
     totalProcessed?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubun/connector",
-  "version": "0.17.2",
+  "version": "0.18.0",
   "keywords": [],
   "license": "see LICENSE.md",
   "sideEffects": false,
@@ -15,10 +15,15 @@
     "LICENSE.md"
   ],
   "dependencies": {
-    "@kubun/credential-types": "^0.17.2",
-    "@kubun/protocol": "^0.17.1",
-    "@kubun/scalars": "^0.17.0",
-    "json-schema-typed": "^8.0.2"
+    "@kokuin/token": "^0.5.1",
+    "@kubun/credential-types": "^0.18.0",
+    "@kubun/hlc": "^0.18.0",
+    "@kubun/id": "^0.18.0",
+    "@kubun/protocol": "^0.18.0",
+    "@kubun/records": "^0.18.0",
+    "@kubun/scalars": "^0.18.0",
+    "@sozai/codec": "^0.4.3",
+    "json-schema-typed": "^9.0.0"
   },
   "publishConfig": {
     "access": "public"