@fabricorg/platform-host 8.0.0 → 8.1.0

package/dist/index.d.cts

@@ -554,6 +554,13 @@ export interface PlatformHostStore<TDb> {
    * optional only for compatibility with existing stores and direct callers.
    */
   updateAdapterInvocation(id: string, patch: Partial<Pick<AdapterInvocationRecord, "status" | "output" | "error" | "attempt" | "updatedAt" | "reconciliation">>, scope?: AdapterInvocationScope): Promise<void>;
+  /**
+   * First-write-wins: an event ID the store already holds, in any tenant or space, is a no-op
+   * that keeps the first event. Do not throw, replace or merge it, regardless of
+   * the later payload, sequence or timestamps. Host re-appends lifecycle events
+   * under stable IDs on retry/recovery with fresh sequences and timestamps and
+   * potentially different payloads.
+   */
   appendEvent(event: AssetEventEnvelope): Promise<void>;
   nextEventSequence(tenantId: string, spaceId: string): Promise<number>;
   /**
@@ -588,7 +595,22 @@ export interface PlatformHostMutationTransaction<TDb> {
    * Required by serialized saga parent lifecycle transitions.
    */
   getEvent?(id: string, tenantId: string, spaceId: string): Promise<AssetEventEnvelope | undefined>;
+  /**
+   * First-write-wins: an event ID the store already holds, in any tenant or space, is a no-op
+   * that keeps the first event. Do not throw, replace or merge it, regardless of
+   * the later payload, sequence or timestamps. Host re-appends lifecycle events
+   * under stable IDs on retry/recovery with fresh sequences and timestamps and
+   * potentially different payloads.
+   */
   appendEvent(event: AssetEventEnvelope): Promise<void>;
+  /**
+   * First-write-wins: an event ID the store already holds, in any tenant or space, is a no-op
+   * that keeps the first event and adds no outbox row, even when the
+   * first append had none. Do not throw,
+   * replace or merge it, regardless of the later payload, sequence or timestamps.
+   * Host re-appends lifecycle events under stable IDs on retry/recovery with fresh
+   * sequences and timestamps and potentially different payloads.
+   */
   appendEventWithOutbox?(event: AssetEventEnvelope, metadata: OutboxEventMetadata): Promise<void>;
   nextEventSequence(tenantId: string, spaceId: string): Promise<number>;
   listEvents(tenantId: string, spaceId: string): Promise<AssetEventEnvelope[]>;
@@ -706,6 +728,14 @@ export interface ClaimOutboxInput {
 export interface OutboxPlatformHostStore<TDb> extends PlatformHostStore<TDb> {
   /** True only when transactionWithEvents supplies appendEventWithOutbox in the same unit of work. */
   readonly transactionalOutbox?: boolean;
+  /**
+   * First-write-wins: an event ID the store already holds, in any tenant or space, is a no-op
+   * that keeps the first event and adds no outbox row, even when the
+   * first append had none. Do not throw,
+   * replace or merge it, regardless of the later payload, sequence or timestamps.
+   * Host re-appends lifecycle events under stable IDs on retry/recovery with fresh
+   * sequences and timestamps and potentially different payloads.
+   */
   appendEventWithOutbox(event: AssetEventEnvelope, metadata: OutboxEventMetadata): Promise<void>;
   claimOutbox(input: ClaimOutboxInput): Promise<OutboxRecord[]>;
   markOutboxPublished(id: string, workerId: string, publishedAt: Date, leaseToken?: number): Promise<void>;
@@ -1766,4 +1796,80 @@ export declare function tenantIsolationChecks(): readonly TenantIsolationCheck[]
 /** Run every check, returning each result rather than throwing on the first. */
 export declare function runTenantIsolationChecks(subject: TenantIsolationSubject): Promise<TenantIsolationResult>;
 //#endregion
+//#region src/event-append-conformance.d.ts
+export interface EventAppendSubject<TDb = unknown> {
+  store: Pick<PlatformHostStore<TDb>, "appendEvent"> & Pick<RecoverablePlatformHostStore<TDb>, "listEvents"> & Partial<Pick<OutboxPlatformHostStore<TDb>, "appendEventWithOutbox" | "listOutbox" | "claimOutbox" | "markOutboxPublished" | "markOutboxFailed">> & Partial<Pick<AtomicMutationPlatformHostStore<TDb>, "transactionWithEvents">>;
+  tenantId: string;
+  /** Optional: restore a known state before a check; probes tolerate accumulated state. */
+  reset?(): Promise<void> | void;
+}
+export interface EventAppendCheck {
+  id: "fabric.store.event-append-first-write-wins.v1" | "fabric.store.event-append-outbox-first-write-wins.v1" | "fabric.store.event-append-outbox-after-plain.v1" | "fabric.store.event-append-transaction-first-write-wins.v1" | "fabric.store.event-append-transaction-outbox-first-write-wins.v1" | "fabric.store.event-append-transaction-outbox-after-plain.v1";
+  run<TDb>(subject: EventAppendSubject<TDb>): Promise<string[]>;
+}
+export interface EventAppendResult {
+  passed: boolean;
+  checks: Array<{
+    id: EventAppendCheck["id"];
+    status: "passed" | "failed" | "skipped";
+    evidence: string[];
+    error?: string;
+  }>;
+}
+/**
+ * Six checks detecting common first-write-wins violations through plain,
+ * outbox and transaction appends, including outbox-after-plain and committed
+ * duplicates: throwing, replacing, merging, keeping both events, selecting the
+ * earlier-ordered or later-ordered duplicate, adding outbox rows, and resetting
+ * or rewriting existing outbox rows in the probed states. They are not exhaustive.
+ * Duplicates have both earlier and later ordering fields and vary the remaining
+ * envelope and outbox metadata fields. Whole-record snapshots compare duplicates
+ * while pending, leased by the probe, retry-pending, and settled as published.
+ * Retry-pending accepts a cleared or expired lease, the probe owner retained
+ * without an expiry, or an expiry within five seconds of the probe's clock,
+ * which is waited out before the row is claimed again; attempt counts and
+ * error formatting are not prescribed.
+ * Initial comparisons accept store-specific fields and fields the store omits
+ * or returns as null; transaction verification runs after commit without requiring
+ * read-your-writes. Each committed duplicate transaction also appends a fresh plain
+ * control event whose presence is verified after commit.
+ * Successful outbox-creating checks leave the probe row
+ * published although nothing was sent; its event-append-probe space identifies
+ * it. Absence checks write a control row that cleanup dead-letters. These rows can
+ * be requeued by operator tooling; exclude probe spaces from real publication.
+ *
+ * Intended for test or staging stores with outbox relays paused for the probe
+ * tenant. Event and availability inputs use whole seconds a few seconds in the
+ * past; claims and publication markers use real current time. Checks leave
+ * append-only events in fresh event-append-probe spaces. Final cleanup
+ * attempts to dead-letter visible probe rows still pending with
+ * "event append probe; never published".
+ * Claims use real current time, a pending-probe-row limit, and a 30-second lease.
+ * A filter-ignoring claim can lease foreign rows and make whatever writes the
+ * claim itself makes (such as incrementing attempts). Checks write nothing to
+ * foreign rows and stop claiming for that run (or that standalone check).
+ * After a filter violation, cleanup can dead-letter only probe rows returned by
+ * that claim, using the probe worker and claim tokens without further claims.
+ * Failures list visible probe rows still pending and instruct manual dead-lettering.
+ * Later outbox checks in the run fail as skipped because of the earlier filter
+ * violation. Leases lapse within 30 seconds
+ * of the claim if the store honours the lease duration.
+ *
+ * Missing append capabilities skip; missing listOutbox, claimOutbox,
+ * markOutboxPublished or markOutboxFailed fails verification/cleanup.
+ * Known limits: rules comparing ordering fields in mixed directions, store-wide
+ * uniqueness across spaces or tenants, the dead-letter state, claims that
+ * lease foreign rows without returning them, buffered merges into fields the
+ * store never returns, and duplicate handling that only holds within one
+ * process. Stores requiring gapless sequences, or unique keys over fields the
+ * control events share with the probe event, can fail falsely.
+ */
+export declare function eventAppendChecks(): readonly EventAppendCheck[];
+/**
+ * Run eventAppendChecks and collect results instead of stopping at the first
+ * failure. Use test or staging stores with relays paused for the probe tenant;
+ * see eventAppendChecks for probe publication markers and cleanup side effects.
+ */
+export declare function runEventAppendChecks<TDb>(subject: EventAppendSubject<TDb>): Promise<EventAppendResult>;
+//#endregion
 export { canonicalJson };

package/dist/index.d.ts

@@ -554,6 +554,13 @@ export interface PlatformHostStore<TDb> {
    * optional only for compatibility with existing stores and direct callers.
    */
   updateAdapterInvocation(id: string, patch: Partial<Pick<AdapterInvocationRecord, "status" | "output" | "error" | "attempt" | "updatedAt" | "reconciliation">>, scope?: AdapterInvocationScope): Promise<void>;
+  /**
+   * First-write-wins: an event ID the store already holds, in any tenant or space, is a no-op
+   * that keeps the first event. Do not throw, replace or merge it, regardless of
+   * the later payload, sequence or timestamps. Host re-appends lifecycle events
+   * under stable IDs on retry/recovery with fresh sequences and timestamps and
+   * potentially different payloads.
+   */
   appendEvent(event: AssetEventEnvelope): Promise<void>;
   nextEventSequence(tenantId: string, spaceId: string): Promise<number>;
   /**
@@ -588,7 +595,22 @@ export interface PlatformHostMutationTransaction<TDb> {
    * Required by serialized saga parent lifecycle transitions.
    */
   getEvent?(id: string, tenantId: string, spaceId: string): Promise<AssetEventEnvelope | undefined>;
+  /**
+   * First-write-wins: an event ID the store already holds, in any tenant or space, is a no-op
+   * that keeps the first event. Do not throw, replace or merge it, regardless of
+   * the later payload, sequence or timestamps. Host re-appends lifecycle events
+   * under stable IDs on retry/recovery with fresh sequences and timestamps and
+   * potentially different payloads.
+   */
   appendEvent(event: AssetEventEnvelope): Promise<void>;
+  /**
+   * First-write-wins: an event ID the store already holds, in any tenant or space, is a no-op
+   * that keeps the first event and adds no outbox row, even when the
+   * first append had none. Do not throw,
+   * replace or merge it, regardless of the later payload, sequence or timestamps.
+   * Host re-appends lifecycle events under stable IDs on retry/recovery with fresh
+   * sequences and timestamps and potentially different payloads.
+   */
   appendEventWithOutbox?(event: AssetEventEnvelope, metadata: OutboxEventMetadata): Promise<void>;
   nextEventSequence(tenantId: string, spaceId: string): Promise<number>;
   listEvents(tenantId: string, spaceId: string): Promise<AssetEventEnvelope[]>;
@@ -706,6 +728,14 @@ export interface ClaimOutboxInput {
 export interface OutboxPlatformHostStore<TDb> extends PlatformHostStore<TDb> {
   /** True only when transactionWithEvents supplies appendEventWithOutbox in the same unit of work. */
   readonly transactionalOutbox?: boolean;
+  /**
+   * First-write-wins: an event ID the store already holds, in any tenant or space, is a no-op
+   * that keeps the first event and adds no outbox row, even when the
+   * first append had none. Do not throw,
+   * replace or merge it, regardless of the later payload, sequence or timestamps.
+   * Host re-appends lifecycle events under stable IDs on retry/recovery with fresh
+   * sequences and timestamps and potentially different payloads.
+   */
   appendEventWithOutbox(event: AssetEventEnvelope, metadata: OutboxEventMetadata): Promise<void>;
   claimOutbox(input: ClaimOutboxInput): Promise<OutboxRecord[]>;
   markOutboxPublished(id: string, workerId: string, publishedAt: Date, leaseToken?: number): Promise<void>;
@@ -1766,4 +1796,80 @@ export declare function tenantIsolationChecks(): readonly TenantIsolationCheck[]
 /** Run every check, returning each result rather than throwing on the first. */
 export declare function runTenantIsolationChecks(subject: TenantIsolationSubject): Promise<TenantIsolationResult>;
 //#endregion
+//#region src/event-append-conformance.d.ts
+export interface EventAppendSubject<TDb = unknown> {
+  store: Pick<PlatformHostStore<TDb>, "appendEvent"> & Pick<RecoverablePlatformHostStore<TDb>, "listEvents"> & Partial<Pick<OutboxPlatformHostStore<TDb>, "appendEventWithOutbox" | "listOutbox" | "claimOutbox" | "markOutboxPublished" | "markOutboxFailed">> & Partial<Pick<AtomicMutationPlatformHostStore<TDb>, "transactionWithEvents">>;
+  tenantId: string;
+  /** Optional: restore a known state before a check; probes tolerate accumulated state. */
+  reset?(): Promise<void> | void;
+}
+export interface EventAppendCheck {
+  id: "fabric.store.event-append-first-write-wins.v1" | "fabric.store.event-append-outbox-first-write-wins.v1" | "fabric.store.event-append-outbox-after-plain.v1" | "fabric.store.event-append-transaction-first-write-wins.v1" | "fabric.store.event-append-transaction-outbox-first-write-wins.v1" | "fabric.store.event-append-transaction-outbox-after-plain.v1";
+  run<TDb>(subject: EventAppendSubject<TDb>): Promise<string[]>;
+}
+export interface EventAppendResult {
+  passed: boolean;
+  checks: Array<{
+    id: EventAppendCheck["id"];
+    status: "passed" | "failed" | "skipped";
+    evidence: string[];
+    error?: string;
+  }>;
+}
+/**
+ * Six checks detecting common first-write-wins violations through plain,
+ * outbox and transaction appends, including outbox-after-plain and committed
+ * duplicates: throwing, replacing, merging, keeping both events, selecting the
+ * earlier-ordered or later-ordered duplicate, adding outbox rows, and resetting
+ * or rewriting existing outbox rows in the probed states. They are not exhaustive.
+ * Duplicates have both earlier and later ordering fields and vary the remaining
+ * envelope and outbox metadata fields. Whole-record snapshots compare duplicates
+ * while pending, leased by the probe, retry-pending, and settled as published.
+ * Retry-pending accepts a cleared or expired lease, the probe owner retained
+ * without an expiry, or an expiry within five seconds of the probe's clock,
+ * which is waited out before the row is claimed again; attempt counts and
+ * error formatting are not prescribed.
+ * Initial comparisons accept store-specific fields and fields the store omits
+ * or returns as null; transaction verification runs after commit without requiring
+ * read-your-writes. Each committed duplicate transaction also appends a fresh plain
+ * control event whose presence is verified after commit.
+ * Successful outbox-creating checks leave the probe row
+ * published although nothing was sent; its event-append-probe space identifies
+ * it. Absence checks write a control row that cleanup dead-letters. These rows can
+ * be requeued by operator tooling; exclude probe spaces from real publication.
+ *
+ * Intended for test or staging stores with outbox relays paused for the probe
+ * tenant. Event and availability inputs use whole seconds a few seconds in the
+ * past; claims and publication markers use real current time. Checks leave
+ * append-only events in fresh event-append-probe spaces. Final cleanup
+ * attempts to dead-letter visible probe rows still pending with
+ * "event append probe; never published".
+ * Claims use real current time, a pending-probe-row limit, and a 30-second lease.
+ * A filter-ignoring claim can lease foreign rows and make whatever writes the
+ * claim itself makes (such as incrementing attempts). Checks write nothing to
+ * foreign rows and stop claiming for that run (or that standalone check).
+ * After a filter violation, cleanup can dead-letter only probe rows returned by
+ * that claim, using the probe worker and claim tokens without further claims.
+ * Failures list visible probe rows still pending and instruct manual dead-lettering.
+ * Later outbox checks in the run fail as skipped because of the earlier filter
+ * violation. Leases lapse within 30 seconds
+ * of the claim if the store honours the lease duration.
+ *
+ * Missing append capabilities skip; missing listOutbox, claimOutbox,
+ * markOutboxPublished or markOutboxFailed fails verification/cleanup.
+ * Known limits: rules comparing ordering fields in mixed directions, store-wide
+ * uniqueness across spaces or tenants, the dead-letter state, claims that
+ * lease foreign rows without returning them, buffered merges into fields the
+ * store never returns, and duplicate handling that only holds within one
+ * process. Stores requiring gapless sequences, or unique keys over fields the
+ * control events share with the probe event, can fail falsely.
+ */
+export declare function eventAppendChecks(): readonly EventAppendCheck[];
+/**
+ * Run eventAppendChecks and collect results instead of stopping at the first
+ * failure. Use test or staging stores with relays paused for the probe tenant;
+ * see eventAppendChecks for probe publication markers and cleanup side effects.
+ */
+export declare function runEventAppendChecks<TDb>(subject: EventAppendSubject<TDb>): Promise<EventAppendResult>;
+//#endregion
 export { canonicalJson };