@propertysimple/client 0.1.0

package/client/src/directory-sync.js

@@ -0,0 +1,404 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { operations, SmartFeedSelectorSchema, SmartFeedResourceSchema, } from '../../contracts/src/index.js';
+import { ApiError } from './index.js';
+import { freshLocationProjection } from '../../contracts/src/location-serving.js';
+import { ProjectionUnavailableError, } from './managed-sync.js';
+const newCheckpoint = () => ({
+    phase: 'create',
+    generation: randomUUID(),
+    lastSequence: '0',
+    visibleSequence: '0',
+});
+const seq = (value) => {
+    if (!/^\d+$/.test(value))
+        throw new Error('Invalid smart-feed sequence.');
+    return BigInt(value);
+};
+const key = (resource) => `${resource.resource_type}:${resource.resource_id}`;
+const afterKey = (value = '') => {
+    if (!value)
+        return ['', ''];
+    const delimiter = value.indexOf(':');
+    const type = value.slice(0, delimiter), id = value.slice(delimiter + 1);
+    if (!['entity', 'listing', 'relationship', 'identity_resolution'].includes(type) ||
+        !id ||
+        id.length > 256)
+        throw new Error('Use a typed resource key for pagination.');
+    return [type, id];
+};
+const serveResource = (payload, at) => {
+    const resource = SmartFeedResourceSchema.parse(payload);
+    return resource.resource_type === 'listing'
+        ? { ...resource, payload: freshLocationProjection(resource.payload, at) }
+        : resource;
+};
+/**
+ * A consumer-owned typed projection. Versions received for an incomplete group are durable but
+ * invisible. Completing a group changes one visibility pointer rather than applying an unbounded
+ * mutation transaction. Product-owned users, leads, slugs and billing never enter this schema.
+ */
+export class PostgresDirectoryTarget {
+    db;
+    configuration;
+    selector;
+    fingerprint;
+    constructor(db, configuration) {
+        this.db = db;
+        this.configuration = configuration;
+        for (const value of [
+            configuration.streamId,
+            configuration.datasetId,
+            configuration.sourceNamespace,
+        ])
+            if (!value || value.length > 256)
+                throw new Error('Sync identities must contain 1–256 characters.');
+        this.selector = SmartFeedSelectorSchema.parse(configuration.selector ?? {});
+        if (this.selector.party_id && this.selector.mode !== 'combined')
+            throw new Error('A party selector requires combined mode.');
+        this.fingerprint = createHash('sha256')
+            .update(JSON.stringify([configuration.datasetId, configuration.sourceNamespace, this.selector]))
+            .digest('hex');
+    }
+    /**
+     * Explicit approved install/upgrade. v2 keeps resource_type as text, adds version metadata,
+     * and invalidates every v1 checkpoint so identity bindings enter through a complete snapshot.
+     * Stable local UUID mappings and old versions remain for product-owned recovery/pruning.
+     * Quiesce old SDK workers before invoking this; initialization is not a request-time action.
+     */
+    async initialize() {
+        await this.db.transaction(async (tx) => {
+            await tx.query(`create schema if not exists consumer_smart_feed;
+        create table if not exists consumer_smart_feed.schema_version(singleton integer primary key check(singleton=1),version integer not null);
+        insert into consumer_smart_feed.schema_version(singleton,version) values(1,1) on conflict do nothing;
+        alter table consumer_smart_feed.schema_version enable row level security;
+        revoke all on consumer_smart_feed.schema_version from public;`);
+            const version = (await tx.query(`select version from consumer_smart_feed.schema_version where singleton=1 for update`)).rows[0].version;
+            if (![1, 2].includes(version))
+                throw new Error('Unsupported consumer smart-feed schema version; use a compatible SDK.');
+            await tx.query(`
+      create table if not exists consumer_smart_feed.streams(id text primary key,fingerprint text not null,version bigint not null default 0,checkpoint jsonb not null,active_generation text,visible_seq bigint not null default 0,synchronized_at timestamptz);
+      create table if not exists consumer_smart_feed.identities(stream_id text not null references consumer_smart_feed.streams(id),resource_type text not null,resource_id text not null,local_id uuid not null,primary key(stream_id,resource_type,resource_id),unique(stream_id,local_id));
+      create table if not exists consumer_smart_feed.versions(stream_id text not null references consumer_smart_feed.streams(id),generation text not null,resource_type text not null,resource_id text not null,sequence bigint not null,payload jsonb,primary key(stream_id,generation,resource_type,resource_id,sequence));
+      create index if not exists smart_feed_projection_read on consumer_smart_feed.versions(stream_id,generation,resource_type,resource_id,sequence desc);
+      create index if not exists smart_feed_projection_changes on consumer_smart_feed.versions(stream_id,generation,sequence);
+      create table if not exists consumer_smart_feed.invalidations(id uuid primary key,stream_id text not null references consumer_smart_feed.streams(id),generation text not null,kind text not null check(kind in('reset','group')),from_sequence bigint not null,through_sequence bigint not null,created_at timestamptz not null default now(),acknowledged_at timestamptz,lease_token uuid,lease_until timestamptz);
+      create index if not exists smart_feed_invalidations_pending on consumer_smart_feed.invalidations(stream_id,created_at) where acknowledged_at is null;
+      alter table consumer_smart_feed.streams enable row level security;
+      alter table consumer_smart_feed.identities enable row level security;
+      alter table consumer_smart_feed.versions enable row level security;
+      alter table consumer_smart_feed.invalidations enable row level security;
+      revoke all on schema consumer_smart_feed from public;
+      revoke all on consumer_smart_feed.streams,consumer_smart_feed.identities,consumer_smart_feed.versions,consumer_smart_feed.invalidations from public;`);
+            if (version === 1) {
+                // A single schema transaction fences old page writers through stream versions,
+                // hides stale projections immediately, and emits durable product invalidations.
+                await tx.query(`with reset as(update consumer_smart_feed.streams set version=version+1,active_generation=null,visible_seq=0,synchronized_at=null,checkpoint=jsonb_build_object('phase','create','generation',gen_random_uuid()::text,'lastSequence','0','visibleSequence','0') returning id,checkpoint)
+        insert into consumer_smart_feed.invalidations(id,stream_id,generation,kind,from_sequence,through_sequence) select gen_random_uuid(),id,checkpoint->>'generation','reset',0,0 from reset`);
+                await tx.query(`update consumer_smart_feed.schema_version set version=2 where singleton=1`);
+            }
+            await tx.query(`insert into consumer_smart_feed.streams(id,fingerprint,checkpoint) values($1,$2,$3::jsonb) on conflict(id) do nothing`, [this.configuration.streamId, this.fingerprint, JSON.stringify(newCheckpoint())]);
+        });
+        await this.state();
+    }
+    async state() {
+        const row = (await this.db.query(`select *,version::text,visible_seq::text from consumer_smart_feed.streams where id=$1`, [this.configuration.streamId])).rows[0];
+        if (!row)
+            throw new Error('Initialize the directory target first.');
+        if (row.fingerprint !== this.fingerprint)
+            throw new Error('Feed scope/selector changed; create a new stream.');
+        return row;
+    }
+    async commit(expected, next, write, options = {}) {
+        return this.db.transaction(async (tx) => {
+            const current = (await tx.query(`select version::text from consumer_smart_feed.streams where id=$1 for update`, [this.configuration.streamId])).rows[0];
+            if (current.version !== expected.version)
+                return false;
+            await write(tx);
+            await tx.query(`update consumer_smart_feed.streams set checkpoint=$2::jsonb,version=version+1,visible_seq=$3,active_generation=case when $4 then $5 else active_generation end,synchronized_at=case when $6 then now() else synchronized_at end where id=$1`, [
+                this.configuration.streamId,
+                JSON.stringify(next),
+                next.visibleSequence,
+                options.activate ?? false,
+                next.generation,
+                options.synchronized ?? false,
+            ]);
+            return true;
+        });
+    }
+    /** Two set-based writes per page, independent of page size. Checkpoint commits in the caller. */
+    async writePage(tx, generation, items) {
+        if (!items.length)
+            return;
+        const records = items.map((row) => ({ ...row, local_id: randomUUID() }));
+        await tx.query(`insert into consumer_smart_feed.identities(stream_id,resource_type,resource_id,local_id) select $1,resource_type,resource_id,local_id from jsonb_to_recordset($2::jsonb) x(resource_type text,resource_id text,local_id uuid) on conflict(stream_id,resource_type,resource_id) do nothing`, [this.configuration.streamId, JSON.stringify(records)]);
+        await tx.query(`insert into consumer_smart_feed.versions(stream_id,generation,resource_type,resource_id,sequence,payload) select $1,$2,resource_type,resource_id,sequence,nullif(resource,'null'::jsonb) from jsonb_to_recordset($3::jsonb) x(resource_type text,resource_id text,sequence bigint,resource jsonb)`, [this.configuration.streamId, generation, JSON.stringify(records)]);
+    }
+    async invalidate(tx, generation, kind, from, through) {
+        await tx.query(`insert into consumer_smart_feed.invalidations(id,stream_id,generation,kind,from_sequence,through_sequence) values($1,$2,$3,$4,$5,$6)`, [randomUUID(), this.configuration.streamId, generation, kind, from, through]);
+    }
+    async reset(expected, blocked = false) {
+        const next = newCheckpoint();
+        if (blocked)
+            next.phase = 'blocked';
+        return this.commit(expected, next, async (tx) => {
+            await tx.query(`update consumer_smart_feed.streams set active_generation=null,synchronized_at=null where id=$1`, [this.configuration.streamId]);
+            await this.invalidate(tx, next.generation, 'reset', '0', '0');
+        });
+    }
+    async resume() {
+        const state = await this.state();
+        if (state.checkpoint.phase !== 'blocked')
+            throw new Error('Only blocked streams require resume.');
+        await this.reset(state);
+    }
+    async mapExistingIdentity(resourceType, resourceId, localId) {
+        await this.db.transaction(async (tx) => {
+            await tx.query(`insert into consumer_smart_feed.identities(stream_id,resource_type,resource_id,local_id) values($1,$2,$3,$4) on conflict(stream_id,resource_type,resource_id) do nothing`, [this.configuration.streamId, resourceType, resourceId, localId]);
+            const row = (await tx.query(`select local_id from consumer_smart_feed.identities where stream_id=$1 and resource_type=$2 and resource_id=$3`, [this.configuration.streamId, resourceType, resourceId])).rows[0];
+            if (row.local_id !== localId.toLowerCase())
+                throw new Error('Existing product identities cannot be remapped.');
+        });
+    }
+    async readable(tx, options) {
+        if (!Number.isFinite(options.maxStalenessMs) || options.maxStalenessMs <= 0)
+            throw new Error('An explicit positive freshness budget is required.');
+        const row = (await tx.query(`select active_generation is not null and synchronized_at>=now()-($2::double precision*interval '1 millisecond') as ready,checkpoint,now()::text as now_at from consumer_smart_feed.streams where id=$1 for share`, [this.configuration.streamId, options.maxStalenessMs])).rows[0];
+        if (!row?.ready)
+            throw new ProjectionUnavailableError();
+        for (const [budget, field] of [
+            [options.maxSourceStalenessMs, 'last_completed_enumeration_at'],
+            [options.maxFullEnumerationStalenessMs, 'last_full_enumeration_at'],
+        ]) {
+            if (budget === undefined)
+                continue;
+            if (!Number.isFinite(budget) || budget <= 0)
+                throw new Error('Source freshness budgets must be positive.');
+            if (!row.checkpoint.sourceFreshness?.length ||
+                row.checkpoint.sourceFreshness.some((source) => {
+                    const at = source[field] ? Date.parse(source[field]) : NaN;
+                    const now = Date.parse(row.now_at);
+                    return !Number.isFinite(at) || now - at > budget || at > now + 60_000;
+                }))
+                throw new ProjectionUnavailableError('Source evidence is outside its freshness budget.');
+        }
+        return new Date(row.now_at);
+    }
+    async list(options) {
+        const limit = options.limit ?? 100;
+        if (!Number.isInteger(limit) || limit < 1 || limit > 200)
+            throw new Error('Read limit must be 1–200.');
+        const [afterType, afterId] = afterKey(options.after);
+        return this.db.transaction(async (tx) => {
+            const at = await this.readable(tx, options);
+            const rows = (await tx.query(`with latest as(select distinct on(v.resource_type,v.resource_id) v.resource_type,v.resource_id,v.payload from consumer_smart_feed.versions v join consumer_smart_feed.streams s on s.id=v.stream_id and s.active_generation=v.generation where s.id=$1 and v.sequence<=s.visible_seq and ($2::text is null or v.resource_type=$2) and (v.resource_type,v.resource_id)>($3,$4) order by v.resource_type,v.resource_id,v.sequence desc) select l.payload,i.local_id from latest l join consumer_smart_feed.identities i on i.stream_id=$1 and i.resource_type=l.resource_type and i.resource_id=l.resource_id where l.payload is not null order by l.resource_type,l.resource_id limit $5`, [this.configuration.streamId, options.resourceType ?? null, afterType, afterId, limit])).rows;
+            return rows.map((row) => ({
+                resource: serveResource(row.payload, at),
+                local_id: row.local_id,
+            }));
+        });
+    }
+    async get(resourceType, resourceId, options) {
+        return this.db.transaction(async (tx) => {
+            const at = await this.readable(tx, options);
+            const row = (await tx.query(`select v.payload from consumer_smart_feed.versions v join consumer_smart_feed.streams s on s.id=v.stream_id and s.active_generation=v.generation where s.id=$1 and v.resource_type=$2 and v.resource_id=$3 and v.sequence<=s.visible_seq order by v.sequence desc limit 1`, [this.configuration.streamId, resourceType, resourceId])).rows[0];
+            return row?.payload ? serveResource(row.payload, at) : null;
+        });
+    }
+    async claimInvalidations(limit = 100, leaseSeconds = 60) {
+        if (!Number.isInteger(limit) ||
+            limit < 1 ||
+            limit > 200 ||
+            !Number.isInteger(leaseSeconds) ||
+            leaseSeconds < 1 ||
+            leaseSeconds > 3600)
+            throw new Error('Invalid invalidation lease bounds.');
+        return (await this.db.query(`with selected as(select id from consumer_smart_feed.invalidations where stream_id=$1 and acknowledged_at is null and (lease_until is null or lease_until<now()) order by created_at,id limit $2 for update skip locked) update consumer_smart_feed.invalidations o set lease_token=$3,lease_until=now()+($4::integer*interval '1 second') from selected where o.id=selected.id returning o.id,o.kind,o.generation,o.from_sequence::text,o.through_sequence::text,o.lease_token`, [this.configuration.streamId, limit, randomUUID(), leaseSeconds])).rows;
+    }
+    /** Page every affected key before acknowledging a group; resolve current state for cache effects. */
+    async invalidationItems(event, after = '', limit = 100) {
+        if (event.kind === 'reset')
+            throw new Error('Reset invalidations require a complete product cache/index rebuild.');
+        if (!Number.isInteger(limit) || limit < 1 || limit > 200)
+            throw new Error('Invalid page size.');
+        const [afterType, afterId] = afterKey(after);
+        return (await this.db.query(`select distinct v.resource_type,v.resource_id from consumer_smart_feed.versions v join consumer_smart_feed.invalidations o on o.stream_id=v.stream_id and o.generation=v.generation where o.id=$1 and o.stream_id=$2 and o.lease_token=$3 and o.lease_until>=now() and o.acknowledged_at is null and v.sequence>=o.from_sequence and v.sequence<=o.through_sequence and(v.resource_type,v.resource_id)>($4,$5) order by v.resource_type,v.resource_id limit $6`, [event.id, this.configuration.streamId, event.lease_token, afterType, afterId, limit])).rows;
+    }
+    async acknowledgeInvalidation(event) {
+        return ((await this.db.query(`update consumer_smart_feed.invalidations set acknowledged_at=now() where id=$1 and stream_id=$2 and lease_token=$3 and lease_until>=now() and acknowledged_at is null`, [event.id, this.configuration.streamId, event.lease_token])).rowCount === 1);
+    }
+    /** Preserve staged groups and unacknowledged invalidations while reclaiming bounded history. */
+    async pruneObsolete(limit = 1000) {
+        if (!Number.isInteger(limit) || limit < 1 || limit > 10000)
+            throw new Error('Invalid pruning bound.');
+        return this.db.transaction(async (tx) => {
+            await tx.query(`select id from consumer_smart_feed.streams where id=$1 for update`, [
+                this.configuration.streamId,
+            ]);
+            return (await tx.query(`delete from consumer_smart_feed.versions where(stream_id,generation,resource_type,resource_id,sequence) in(
+        select v.stream_id,v.generation,v.resource_type,v.resource_id,v.sequence from consumer_smart_feed.versions v join consumer_smart_feed.streams s on s.id=v.stream_id
+        where s.id=$1 and not exists(select 1 from consumer_smart_feed.invalidations o where o.stream_id=v.stream_id and o.generation=v.generation and o.acknowledged_at is null and(o.kind='reset' or v.sequence between o.from_sequence and o.through_sequence))
+        and((v.generation is distinct from s.active_generation and v.generation<>s.checkpoint->>'generation') or(v.generation=s.active_generation and v.sequence<=s.visible_seq and exists(select 1 from consumer_smart_feed.versions n where n.stream_id=v.stream_id and n.generation=v.generation and n.resource_type=v.resource_type and n.resource_id=v.resource_id and n.sequence>v.sequence and n.sequence<=s.visible_seq))) limit $2)`, [this.configuration.streamId, limit])).rowCount;
+        });
+    }
+}
+export class DirectorySyncWorker {
+    source;
+    target;
+    pageSize;
+    constructor(source, target, pageSize = 100) {
+        this.source = source;
+        this.target = target;
+        this.pageSize = pageSize;
+        if (!Number.isInteger(pageSize) || pageSize < 1 || pageSize > 200)
+            throw new Error('Feed page size must be 1–200.');
+    }
+    async step(options = {}) {
+        const state = await this.target.state(), checkpoint = state.checkpoint;
+        const result = (status, applied = 0) => ({ status, applied });
+        if (checkpoint.phase === 'blocked')
+            return result('blocked');
+        try {
+            if (checkpoint.phase === 'create') {
+                const snapshot = operations.createDirectorySnapshot.output.parse(await this.source.directory.createSnapshot({ dataset_id: this.target.configuration.datasetId, ...this.target.selector }, { ...options, idempotencyKey: `smart-feed-snapshot-${checkpoint.generation}` }));
+                if (snapshot.dataset_id !== this.target.configuration.datasetId ||
+                    JSON.stringify(snapshot.selector) !== JSON.stringify(this.target.selector))
+                    throw new Error('Feed snapshot scope differs from the requested stream.');
+                if (snapshot.status === 'expired')
+                    return result((await this.target.reset(state)) ? 'reset' : 'conflict');
+                seq(snapshot.snapshot_sequence);
+                const next = {
+                    ...checkpoint,
+                    phase: 'snapshot',
+                    snapshotId: snapshot.id,
+                    snapshotSequence: snapshot.snapshot_sequence,
+                    lastSequence: snapshot.snapshot_sequence,
+                    visibleSequence: snapshot.snapshot_sequence,
+                    replayCursor: snapshot.replay_cursor,
+                };
+                return result((await this.target.commit(state, next, async () => { })) ? 'progress' : 'conflict');
+            }
+            if (checkpoint.phase === 'snapshot') {
+                const page = operations.listDirectorySnapshotItems.output.parse(await this.source.directory.snapshotItems(checkpoint.snapshotId, {
+                    limit: this.pageSize,
+                    ...(checkpoint.snapshotCursor ? { cursor: checkpoint.snapshotCursor } : {}),
+                }, options));
+                if (page.data.length > this.pageSize ||
+                    page.meta.snapshot_sequence !== checkpoint.snapshotSequence ||
+                    new Set(page.data.map(key)).size !== page.data.length ||
+                    (page.has_more &&
+                        (!page.data.length ||
+                            !page.next_cursor ||
+                            page.next_cursor === checkpoint.snapshotCursor)))
+                    throw new Error('Invalid feed snapshot pagination.');
+                const next = {
+                    ...checkpoint,
+                    phase: page.has_more ? 'snapshot' : 'replay',
+                    ...(page.has_more ? { snapshotCursor: page.next_cursor } : {}),
+                    sourceFreshness: page.meta.source_freshness,
+                };
+                const saved = await this.target.commit(state, next, (tx) => this.target.writePage(tx, checkpoint.generation, page.data.map((resource) => ({
+                    resource_type: resource.resource_type,
+                    resource_id: resource.resource_id,
+                    sequence: checkpoint.snapshotSequence,
+                    resource,
+                }))));
+                return result(saved ? 'progress' : 'conflict', saved ? page.data.length : 0);
+            }
+            const page = operations.listDirectoryChanges.output.parse(await this.source.directory.changes({
+                dataset_id: this.target.configuration.datasetId,
+                ...this.target.selector,
+                cursor: checkpoint.replayCursor,
+                limit: this.pageSize,
+            }, options));
+            if (page.data.length > this.pageSize ||
+                (page.has_more && !page.data.length) ||
+                (page.data.length && page.next_cursor === checkpoint.replayCursor))
+                throw new Error('Invalid feed replay pagination.');
+            const next = structuredClone(checkpoint), completed = [];
+            for (const change of page.data) {
+                this.validateChange(change, next);
+                if (!next.group)
+                    next.group = {
+                        id: change.group_id,
+                        end: change.group_end_sequence,
+                        size: change.group_size,
+                        next: 0,
+                        start: change.sequence,
+                    };
+                const group = next.group;
+                if (group.id !== change.group_id ||
+                    group.end !== change.group_end_sequence ||
+                    group.size !== change.group_size ||
+                    group.next !== change.group_index)
+                    throw new Error('Incomplete, reordered or changed feed commit group.');
+                group.next++;
+                next.lastSequence = change.sequence;
+                if (group.next === group.size) {
+                    next.visibleSequence = group.end;
+                    completed.push({ from: group.start, through: group.end });
+                    delete next.group;
+                }
+            }
+            if (!page.has_more && next.group)
+                throw new Error('Feed ended before its commit group completed.');
+            if (seq(page.meta.published_sequence) < seq(next.lastSequence))
+                throw new Error('Feed watermark is behind its changes.');
+            next.replayCursor = page.next_cursor;
+            next.sourceFreshness = page.meta.source_freshness;
+            if (!page.has_more)
+                next.visibleSequence = page.meta.published_sequence;
+            const activate = !page.has_more && state.active_generation !== checkpoint.generation;
+            const saved = await this.target.commit(state, next, async (tx) => {
+                await this.target.writePage(tx, checkpoint.generation, page.data.map((change) => ({
+                    resource_type: change.resource_type,
+                    resource_id: change.resource_id,
+                    sequence: change.sequence,
+                    resource: change.resource,
+                })));
+                if (activate)
+                    await this.target.invalidate(tx, checkpoint.generation, 'reset', '0', next.visibleSequence);
+                else if (state.active_generation === checkpoint.generation)
+                    for (const group of completed)
+                        await this.target.invalidate(tx, checkpoint.generation, 'group', group.from, group.through);
+            }, { activate, synchronized: !page.has_more });
+            return result(saved ? (page.data.length || page.has_more ? 'progress' : 'idle') : 'conflict', saved ? page.data.length : 0);
+        }
+        catch (error) {
+            if (error instanceof ApiError && error.status === 410)
+                return result((await this.target.reset(state)) ? 'reset' : 'conflict');
+            if (error instanceof ApiError && [401, 403].includes(error.status))
+                await this.target.reset(state, true);
+            throw error;
+        }
+    }
+    validateChange(change, checkpoint) {
+        if (seq(change.sequence) <= seq(checkpoint.lastSequence) ||
+            seq(change.group_end_sequence) < seq(change.sequence) ||
+            change.group_index >= change.group_size)
+            throw new Error('Invalid feed sequence/group boundaries.');
+        if (!checkpoint.group && change.group_index !== 0)
+            throw new Error('Feed commit group starts in the middle.');
+        if (!checkpoint.group && seq(change.sequence) <= seq(checkpoint.visibleSequence))
+            throw new Error('Feed commit groups overlap.');
+        if (change.operation === 'remove' && change.resource !== null)
+            throw new Error('A removal cannot carry a resource.');
+        if (change.operation === 'upsert' &&
+            (!change.resource ||
+                change.resource.resource_id !== change.resource_id ||
+                change.resource.resource_type !== change.resource_type ||
+                change.resource.revision !== change.revision))
+            throw new Error('Feed resource identity/revision mismatch.');
+    }
+    async run(options) {
+        if (!Number.isInteger(options.maxSteps) || options.maxSteps < 1 || options.maxSteps > 10000)
+            throw new Error('A bounded maxSteps is required.');
+        const results = [];
+        for (let count = 0; count < options.maxSteps; count++) {
+            const result = await this.step(options);
+            results.push(result);
+            if (['idle', 'blocked', 'conflict'].includes(result.status))
+                break;
+        }
+        return results;
+    }
+}