@cotal-ai/connector-core 0.68.0 → 0.70.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/agent.d.ts +10 -2
- package/dist/agent.d.ts.map +1 -1
- package/dist/agent.js +21 -27
- package/dist/agent.js.map +1 -1
- package/dist/agui-emitter.d.ts +318 -0
- package/dist/agui-emitter.d.ts.map +1 -0
- package/dist/agui-emitter.js +706 -0
- package/dist/agui-emitter.js.map +1 -0
- package/dist/agui-holder.d.ts +59 -28
- package/dist/agui-holder.d.ts.map +1 -1
- package/dist/agui-holder.js +29 -36
- package/dist/agui-holder.js.map +1 -1
- package/dist/agui.d.ts +19 -318
- package/dist/agui.d.ts.map +1 -1
- package/dist/agui.js +15 -707
- package/dist/agui.js.map +1 -1
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +10 -7
- package/dist/config.js.map +1 -1
- package/dist/docs-bundle.generated.d.ts +1 -1
- package/dist/docs-bundle.generated.js +27 -27
- package/dist/docs-bundle.generated.js.map +1 -1
- package/dist/event-wal.d.ts +38 -44
- package/dist/event-wal.d.ts.map +1 -1
- package/dist/event-wal.js +105 -124
- package/dist/event-wal.js.map +1 -1
- package/dist/framing.d.ts +1 -18
- package/dist/framing.d.ts.map +1 -1
- package/dist/framing.js +20 -3
- package/dist/framing.js.map +1 -1
- package/dist/index.d.ts +1 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -0
- package/dist/index.js.map +1 -1
- package/dist/orientation.d.ts +2 -2
- package/dist/orientation.d.ts.map +1 -1
- package/dist/orientation.js +17 -4
- package/dist/orientation.js.map +1 -1
- package/dist/tool-specs.d.ts.map +1 -1
- package/dist/tool-specs.js +9 -29
- package/dist/tool-specs.js.map +1 -1
- package/package.json +2 -2
package/dist/agui.d.ts
CHANGED
|
@@ -23,25 +23,20 @@
|
|
|
23
23
|
* ## What is here, and what is deliberately NOT
|
|
24
24
|
*
|
|
25
25
|
* Here: the event constructors, the frame envelope, the routing/validity split
|
|
26
|
-
* ({@link isAguiFramePart} / {@link parseAguiFrame}), the {@link AguiBrackets} stream machine,
|
|
27
|
-
*
|
|
26
|
+
* ({@link isAguiFramePart} / {@link parseAguiFrame}), the {@link AguiBrackets} stream machine, the
|
|
27
|
+
* `cotal.*` `CUSTOM` table (empty in v1), the preview plane's {@link splitFrames}, and the egress
|
|
28
|
+
* policy that decides which events may leave for the event channel.
|
|
28
29
|
*
|
|
29
|
-
* Not here
|
|
30
|
-
*
|
|
31
|
-
*
|
|
30
|
+
* Not here: the emitter that publishes, with the channel derivation and the durable source, WAL and
|
|
31
|
+
* subject frontier it drives. Those are in `agui-emitter.ts`, which imports this module and is never
|
|
32
|
+
* imported by it, so a change to the delivery machine cannot reach the vocabulary.
|
|
32
33
|
*
|
|
33
|
-
* **
|
|
34
|
-
*
|
|
35
|
-
* tree, not a disclaimer — a reader deciding whether a change here can reach a customer needs it to
|
|
36
|
-
* be accurate, so it is maintained rather than left to rot.
|
|
34
|
+
* **This module publishes nothing and does no I/O.** A reader deciding whether a change here can
|
|
35
|
+
* reach the wire on its own needs that to be accurate, so it is maintained rather than left to rot.
|
|
37
36
|
*/
|
|
38
37
|
import type { CustomEvent, ReasoningMessageContentEvent, ReasoningMessageEndEvent, ReasoningMessageStartEvent, RunErrorEvent, RunFinishedEvent, RunStartedEvent, TextMessageContentEvent, TextMessageEndEvent, TextMessageStartEvent, ToolCallArgsEvent, ToolCallEndEvent, ToolCallResultEvent, ToolCallStartEvent } from "@ag-ui/core";
|
|
39
38
|
export { AGUI_FRAME_KIND, AGUI_EVENT_TYPE, isAguiFramePart } from "@cotal-ai/core";
|
|
40
39
|
import { AGUI_FRAME_KIND } from "@cotal-ai/core";
|
|
41
|
-
import { type Part } from "@cotal-ai/core";
|
|
42
|
-
import type { DurableSource } from "./durable-source.js";
|
|
43
|
-
import type { SubjectFrontier } from "./subject-frontier.js";
|
|
44
|
-
import type { EventWal } from "./event-wal.js";
|
|
45
40
|
/**
|
|
46
41
|
* The AG-UI events this plane emits — the MAPPED SUBSET, not the whole protocol.
|
|
47
42
|
*
|
|
@@ -472,12 +467,17 @@ export declare function reasoningMessageEnd(o: {
|
|
|
472
467
|
timestamp: number;
|
|
473
468
|
cotal?: CotalMeta;
|
|
474
469
|
}): WithCotal<ReasoningMessageEndEvent>;
|
|
470
|
+
/** Truncate to `codePoints` code points, never code UNITS. Slicing a JS string by index can cut a
|
|
471
|
+
* surrogate pair in half and produce a lone surrogate, which is not well-formed UTF-16 — the exact
|
|
472
|
+
* defect `fix(core)!: refuse names that are not well-formed UTF-16` landed on this branch for. A
|
|
473
|
+
* splitter that reintroduced it here would emit a frame the wire layer is now obliged to refuse. */
|
|
474
|
+
export declare const takeCodePoints: (s: string, codePoints: number) => string;
|
|
475
475
|
/**
|
|
476
476
|
* Split `events` into as many frames as the wire requires, truncating only what physically cannot
|
|
477
477
|
* cross it, and LABELLING every truncation.
|
|
478
478
|
*
|
|
479
479
|
* **THIS IS THE PREVIEW PLANE'S SPLITTER, AND IT HAS NO DURABLE-PLANE CALLER BY DESIGN.**
|
|
480
|
-
* Read that as a boundary, not as an oversight: the durable emitter packs with
|
|
480
|
+
* Read that as a boundary, not as an oversight: the durable emitter packs with `packUnits` at
|
|
481
481
|
* SOURCE-RECORD boundaries and refuses an oversized unit, because one durable emit unit must be one
|
|
482
482
|
* frame carrying a cursor that resumes after it, and a frame ending mid-record has no cursor it can
|
|
483
483
|
* honestly store. This event-boundary split and its labelled truncation were specified before the
|
|
@@ -486,10 +486,11 @@ export declare function reasoningMessageEnd(o: {
|
|
|
486
486
|
* right answer and why this machinery is worth keeping.
|
|
487
487
|
*
|
|
488
488
|
* **Calling this from the durable emitter would be a silent-loss bug**, not a performance choice —
|
|
489
|
-
* so if you are here looking for the packer, you want `packUnits`. And it is
|
|
490
|
-
* deleted for the reason one module over already demonstrated:
|
|
491
|
-
* with zero production callers looking exactly like live code,
|
|
492
|
-
* is a hazard whichever direction the next reader resolves it
|
|
489
|
+
* so if you are here looking for the packer, you want `packUnits` in `agui-emitter.ts`. And it is
|
|
490
|
+
* marked rather than deleted for the reason one module over already demonstrated:
|
|
491
|
+
* `assertExpectationSemantics()` sat with zero production callers looking exactly like live code,
|
|
492
|
+
* and unreachable code that looks live is a hazard whichever direction the next reader resolves it
|
|
493
|
+
* in.
|
|
493
494
|
*
|
|
494
495
|
* **Say the uncomfortable thing:** this is a content truncation, which is one of the
|
|
495
496
|
* sins `tr-` is being abolished for. The difference is not that we are gentler about it. `tr-` cut
|
|
@@ -526,122 +527,6 @@ export declare function splitFrames(opts: {
|
|
|
526
527
|
measure: (frame: AguiFrame) => number;
|
|
527
528
|
limit: number;
|
|
528
529
|
}): AguiFrame[];
|
|
529
|
-
/**
|
|
530
|
-
* The endpoint surface the emitter needs, declared STRUCTURALLY rather than as `CotalEndpoint`.
|
|
531
|
-
*
|
|
532
|
-
* Not for testability as an end in itself — for a specific one. A cell that needs a live broker to
|
|
533
|
-
* exercise the duplicate-ack halt cannot be written at all before a broker exists, and a cell that
|
|
534
|
-
* re-implements `encodedSize` is measuring a copy. This interface is the exact set of methods the
|
|
535
|
-
* emitter calls, so a cell substitutes an instrument and the production path substitutes the real
|
|
536
|
-
* endpoint, and neither one is a re-implementation of the other.
|
|
537
|
-
*/
|
|
538
|
-
export interface EmitterEndpoint {
|
|
539
|
-
readonly principal: {
|
|
540
|
-
owner: string;
|
|
541
|
-
actor: string;
|
|
542
|
-
};
|
|
543
|
-
readonly actorIsEphemeral: boolean;
|
|
544
|
-
/** The broker's live `max_payload`. Throws when not connected — never guesses a default. */
|
|
545
|
-
readonly maxPayload: number;
|
|
546
|
-
/** The single-replica preflight. The emitter calls this at startup, before anything can publish. */
|
|
547
|
-
assertExpectationSemantics(): Promise<void>;
|
|
548
|
-
encodedSize(o: {
|
|
549
|
-
channel: string;
|
|
550
|
-
parts: Part[];
|
|
551
|
-
id: string;
|
|
552
|
-
expectedLastSubjectSeq: number;
|
|
553
|
-
}): number;
|
|
554
|
-
multicastExpecting(o: {
|
|
555
|
-
channel: string;
|
|
556
|
-
parts: Part[];
|
|
557
|
-
id: string;
|
|
558
|
-
expectedLastSubjectSeq: number;
|
|
559
|
-
}): Promise<{
|
|
560
|
-
ack: {
|
|
561
|
-
seq: number;
|
|
562
|
-
duplicate: boolean;
|
|
563
|
-
};
|
|
564
|
-
}>;
|
|
565
|
-
}
|
|
566
|
-
/**
|
|
567
|
-
* One source record's worth of events, with the cursor that resumes AFTER that record.
|
|
568
|
-
*
|
|
569
|
-
* One durable emit unit is one frame: the emitter splits only at source-observation boundaries that
|
|
570
|
-
* are independently reconstructable from the durable source. A frame therefore ends where a record
|
|
571
|
-
* ends, and carries that record's cursor, so folding it means exactly "every record here is
|
|
572
|
-
* consumed".
|
|
573
|
-
*/
|
|
574
|
-
export interface EmitUnit {
|
|
575
|
-
/** The run these events belong to. A frame's envelope names ONE run, so units are never
|
|
576
|
-
* mixed across runs in one frame. */
|
|
577
|
-
runId: string;
|
|
578
|
-
events: AguiEvent[];
|
|
579
|
-
cursor: string;
|
|
580
|
-
}
|
|
581
|
-
/** What the mapper returns for one source record: its run and its events, or `null` for a record
|
|
582
|
-
* this plane deliberately drops, and it drops many. `null` is NOT an error: a deliberate drop and
|
|
583
|
-
* a failed map are kept apart, because conflating them turns a parser bug into skipped history. */
|
|
584
|
-
export type RecordMapper<T> = (record: T) => {
|
|
585
|
-
runId: string;
|
|
586
|
-
events: AguiEvent[];
|
|
587
|
-
} | null;
|
|
588
|
-
/**
|
|
589
|
-
* A bracket violation that is OURS, not the writer's: the machine that tracks open runs and messages
|
|
590
|
-
* was lost across a process restart.
|
|
591
|
-
*
|
|
592
|
-
* **This exists because two halts that both say "unbalanced" prove nothing about which produced
|
|
593
|
-
* one.** The WAL persists `epoch`, `frontier` and the pending frame, and NOT the set of open
|
|
594
|
-
* runs and messages, so a process that dies mid-run restarts with an empty {@link AguiBrackets},
|
|
595
|
-
* resumes from `sourceCursor` at events whose `RUN_STARTED` was already published, and refuses the
|
|
596
|
-
* first of them. Without this class the operator sees "nothing may be emitted outside an open run"
|
|
597
|
-
* and files a bug against a writer that did nothing wrong.
|
|
598
|
-
*
|
|
599
|
-
* It is deliberately a SUBCLASS: every existing catch of {@link AguiVocabularyError} still catches
|
|
600
|
-
* it, and only code that wants to tell the two apart has to know it exists.
|
|
601
|
-
*/
|
|
602
|
-
export declare class AguiBracketStateLost extends AguiVocabularyError {
|
|
603
|
-
readonly cause: Error;
|
|
604
|
-
constructor(message: string, cause: Error);
|
|
605
|
-
}
|
|
606
|
-
/**
|
|
607
|
-
* The emitter has stopped and will not publish again without operator action.
|
|
608
|
-
*
|
|
609
|
-
* Halting is a SUCCESS of this design, not a failure of it: every halt below is a case where the
|
|
610
|
-
* alternative is to report success for a message that was not stored, or to fold an ack for a body
|
|
611
|
-
* we did not write. A halt is loud, bounded and recoverable by a human; the alternative is silent
|
|
612
|
-
* and permanent.
|
|
613
|
-
*/
|
|
614
|
-
export declare class AguiEmitterHalted extends Error {
|
|
615
|
-
readonly reason: "duplicate-ack" | "cas-loss" | "egress-policy" | "egress-unreadable" | "egress-extra-property" | "egress-run-error";
|
|
616
|
-
constructor(reason: "duplicate-ack" | "cas-loss" | "egress-policy" | "egress-unreadable" | "egress-extra-property" | "egress-run-error", message: string);
|
|
617
|
-
}
|
|
618
|
-
/**
|
|
619
|
-
* Pack units into frames, splitting ONLY at unit boundaries and never inside one.
|
|
620
|
-
*
|
|
621
|
-
* Deliberately NOT {@link splitFrames}, and the difference is the durable plane's one-unit-one-frame
|
|
622
|
-
* rule. `splitFrames` splits at EVENT boundaries, which is the right answer for a frame considered
|
|
623
|
-
* on its own, but a frame that ends mid-record has no cursor it can honestly store: the only value
|
|
624
|
-
* available says the whole record was consumed, and folding that after a crash skips the rest of the
|
|
625
|
-
* record's events with no `seq` gap for a consumer to notice.
|
|
626
|
-
*
|
|
627
|
-
* **So the event-boundary split and the one-unit-one-frame rule are in tension, and this resolves it
|
|
628
|
-
* in the direction the durable plane requires: a single unit that does not fit FAILS LOUD rather
|
|
629
|
-
* than being truncated at a frame boundary.** That leaves `splitFrames`'s truncation path with no
|
|
630
|
-
* caller on the durable plane, which is reported as a design conflict rather than decided here.
|
|
631
|
-
*
|
|
632
|
-
* @throws {AguiVocabularyError} when one unit cannot fit in a frame alone.
|
|
633
|
-
*/
|
|
634
|
-
export declare function packUnits(opts: {
|
|
635
|
-
threadId: string;
|
|
636
|
-
epoch: string;
|
|
637
|
-
firstSeq: number;
|
|
638
|
-
units: readonly EmitUnit[];
|
|
639
|
-
measure: (frame: AguiFrame) => number;
|
|
640
|
-
limit: number;
|
|
641
|
-
}): {
|
|
642
|
-
frame: AguiFrame;
|
|
643
|
-
cursor: string;
|
|
644
|
-
}[];
|
|
645
530
|
/**
|
|
646
531
|
* Find the first extra property on a parsed frame, returning its JSON-path
|
|
647
532
|
* string, or `undefined` when the envelope is closed.
|
|
@@ -732,188 +617,4 @@ export type FrozenBodyEgressVerdict = "clean" | "forbidden-kind" | "unreadable"
|
|
|
732
617
|
* `readonly unknown[]`.
|
|
733
618
|
*/
|
|
734
619
|
export declare function frozenBodyEgressVerdict(body: readonly unknown[]): FrozenBodyEgressVerdict;
|
|
735
|
-
/**
|
|
736
|
-
* The event emitter: one per principal, one thread at a time.
|
|
737
|
-
*
|
|
738
|
-
* **BRACKET STATE SURVIVES A RESTART, AND THIS PARAGRAPH USED TO SAY THE OPPOSITE.** It described a
|
|
739
|
-
* declared gap — an emitter coming back with an empty machine, resuming at events whose
|
|
740
|
-
* `RUN_STARTED` had already been published, and refusing the first of them — long after the WAL
|
|
741
|
-
* started persisting the machine. The words were true when they were written and stayed on the page
|
|
742
|
-
* through the change that falsified them, which is the failure mode a class header is worst at
|
|
743
|
-
* showing: it is the first thing a cutover author reads about recovery, and it was telling them to
|
|
744
|
-
* expect a halt the code no longer produces.
|
|
745
|
-
*
|
|
746
|
-
* What actually happens: {@link AguiBrackets} is a property of the WRITER'S STREAM across frames, so
|
|
747
|
-
* the WAL freezes the machine's state WITH each pending frame and promotes it on fold. A restart
|
|
748
|
-
* therefore reopens knowing exactly which run, messages and tool calls were open at the last FOLDED
|
|
749
|
-
* position, and {@link AguiBrackets.restore} continues from there rather than from empty.
|
|
750
|
-
*
|
|
751
|
-
* **The lost-state path still exists, and it is now the narrow case it should always have been:** a
|
|
752
|
-
* document that CANNOT SAY what was open. That is a WAL migrated from v1, which recorded no bracket
|
|
753
|
-
* state at all, and it loads as `null` rather than as an empty machine precisely so the difference
|
|
754
|
-
* stays visible. Only there does the emitter start empty, resume into an already-open run, and
|
|
755
|
-
* refuse the first event with {@link AguiBracketStateLost} — a halt rather than a loss, which is the
|
|
756
|
-
* safe direction, and diagnosed by name rather than surfacing as an anonymous protocol violation.
|
|
757
|
-
*/
|
|
758
|
-
export declare class AguiEmitter<T> {
|
|
759
|
-
private readonly ep;
|
|
760
|
-
private readonly wal;
|
|
761
|
-
private readonly source;
|
|
762
|
-
private readonly map;
|
|
763
|
-
/** Derived from the endpoint's OWN principal, never from a config name or the launch env. */
|
|
764
|
-
readonly channel: string;
|
|
765
|
-
readonly threadId: string;
|
|
766
|
-
/**
|
|
767
|
-
* The bracket machine AT THE FOLDED POSITION — deliberately not "wherever validation got to".
|
|
768
|
-
*
|
|
769
|
-
* It advances one frame at a time, immediately before that frame's `beginSend`, so the state
|
|
770
|
-
* frozen with a pending frame is the state that belongs to it. A machine advanced by the whole
|
|
771
|
-
* batch up front would freeze a state describing events that had not been sent.
|
|
772
|
-
*/
|
|
773
|
-
private brackets;
|
|
774
|
-
private halted;
|
|
775
|
-
/** True once THIS process has fed an event through the bracket machine. It is the half of the
|
|
776
|
-
* restart diagnosis that keeps a genuine mid-stream violation from being blamed on a restart. */
|
|
777
|
-
private fedAnyEvent;
|
|
778
|
-
private constructor();
|
|
779
|
-
/**
|
|
780
|
-
* Start an emitter: resolve the channel, run the single-replica preflight, and settle any pending
|
|
781
|
-
* frame.
|
|
782
|
-
*
|
|
783
|
-
* **THIS IS THAT PREFLIGHT'S PRODUCTION CALL SITE, AND UNTIL THIS FUNCTION EXISTED THERE WAS
|
|
784
|
-
* NONE.** `CotalEndpoint.assertExpectationSemantics()` had zero production callers: it was a
|
|
785
|
-
* check that shipped, was covered by its own suite, and never ran outside one. That is why it is
|
|
786
|
-
* called HERE, before recovery and therefore before any publish — a serialized append on an
|
|
787
|
-
* unverified stream is the exact case it exists to prevent, and doing it after recovery would
|
|
788
|
-
* leave the one publish that matters most, the re-publish of a frozen frame, outside the guard.
|
|
789
|
-
*/
|
|
790
|
-
static start<T>(opts: {
|
|
791
|
-
endpoint: EmitterEndpoint;
|
|
792
|
-
/** Already open, so the caller owns `space`, the WAL path, and the `subjectMayExist` judgement
|
|
793
|
-
* — none of which the emitter can make honestly on the caller's behalf. */
|
|
794
|
-
wal: EventWal;
|
|
795
|
-
/**
|
|
796
|
-
* The PRINCIPAL-scoped subject frontier. **Required, and not optional with a zero default.**
|
|
797
|
-
*
|
|
798
|
-
* The subject is shared by every thread of one principal, so the expectation a publish carries
|
|
799
|
-
* is a fact about the principal and not about the thread. An optional parameter here would let
|
|
800
|
-
* a new connector omit it and reintroduce, silently, the defect where an agent's second session
|
|
801
|
-
* expects an empty subject its own first session filled. There is one thing to pass and there
|
|
802
|
-
* is no legal way to not pass it.
|
|
803
|
-
*/
|
|
804
|
-
subjectFrontier: SubjectFrontier;
|
|
805
|
-
source: DurableSource<T>;
|
|
806
|
-
map: RecordMapper<T>;
|
|
807
|
-
}): Promise<AguiEmitter<T>>;
|
|
808
|
-
/** True once the emitter has stopped for good. */
|
|
809
|
-
get stopped(): boolean;
|
|
810
|
-
/** The run {@link closeRun} would close now, or `undefined` at a stopping point. */
|
|
811
|
-
get openRunId(): string | undefined;
|
|
812
|
-
/**
|
|
813
|
-
* Boot recovery, branching on the WAL's tag.
|
|
814
|
-
*
|
|
815
|
-
* `acked` NEVER republishes: the frame landed and we know it, so the only remaining work is to
|
|
816
|
-
* fold. `sent_unacked` is the genuinely uncertain case and republishes with the SAME frozen `id`
|
|
817
|
-
* and `E` — never the current tip, because re-deriving either is what turns an uncertain publish
|
|
818
|
-
* into a second, different message.
|
|
819
|
-
*/
|
|
820
|
-
private recover;
|
|
821
|
-
/**
|
|
822
|
-
* Read forward, map, pack, and publish. Returns what it did, so a caller can distinguish "nothing
|
|
823
|
-
* to do" from "did work" without inspecting the WAL.
|
|
824
|
-
*/
|
|
825
|
-
pump(): Promise<{
|
|
826
|
-
frames: number;
|
|
827
|
-
events: number;
|
|
828
|
-
}>;
|
|
829
|
-
/**
|
|
830
|
-
* Close the run this stream currently has open, at a boundary the RECORD STREAM CANNOT SEE.
|
|
831
|
-
*
|
|
832
|
-
* **This exists because the two halves of the mapping were specified against different inputs.**
|
|
833
|
-
* The plan sources `RUN_FINISHED` from a harness lifecycle hook, and the durable plane reads a
|
|
834
|
-
* FILE: a hook fires in another process and writes no record, so a hook-sourced terminal has no
|
|
835
|
-
* vehicle into a record-sourced stream. Deriving the terminal from records instead is possible but
|
|
836
|
-
* lies about time in two ways that matter to a live view: the finish lands only when the NEXT turn
|
|
837
|
-
* starts, so a finished agent renders as still running, and the last run of a session never closes
|
|
838
|
-
* at all, because there is no later record to close it on. This is that vehicle.
|
|
839
|
-
*
|
|
840
|
-
* It is a FRAME LIKE ANY OTHER: same epoch, same `seq` line, same write-ahead discipline, same
|
|
841
|
-
* halt rules. The single thing that differs is the cursor, which is republished UNCHANGED, because
|
|
842
|
-
* this frame consumes no source record. A frame that advanced the cursor here would mark records
|
|
843
|
-
* consumed that were never mapped.
|
|
844
|
-
*
|
|
845
|
-
* Idempotent by construction rather than by a flag: the bracket machine is the only state it
|
|
846
|
-
* reads, so once the run is closed there is nothing open to close and it answers `null`. That also
|
|
847
|
-
* makes it safe on a stream whose run was opened by a PREVIOUS process, since the machine is
|
|
848
|
-
* restored from the WAL.
|
|
849
|
-
*
|
|
850
|
-
* **AN `error` CLOSES THE SAME RUN WITH `RUN_ERROR` INSTEAD, and it is one method rather than two
|
|
851
|
-
* ON PURPOSE.** `RUN_ERROR` closes a run on its own, so a run that emitted one must never also
|
|
852
|
-
* emit a `RUN_FINISHED`. With a second method that invariant would be a rule someone has to
|
|
853
|
-
* remember; with one method and one branch it is a property of the shape: exactly one terminal is
|
|
854
|
-
* built, and the bracket machine has closed the run by the time anything could ask for another, so
|
|
855
|
-
* a following close answers `null` like any other close on a settled stream. Which harness signals
|
|
856
|
-
* mean a turn FAILED is a connector's decision and is stated at each connector's own mapping site;
|
|
857
|
-
* this file only carries the answer to the wire.
|
|
858
|
-
*
|
|
859
|
-
* **`error.message` AND `error.code` NEVER REACH THE WIRE.** Both are upstream values, so the close
|
|
860
|
-
* publishes {@link RUN_ERROR_EGRESS_MESSAGE} with no code, the same shape the write path's
|
|
861
|
-
* {@link egressRunError} produces (#1431). The frame bound still runs after that, so a close whose
|
|
862
|
-
* envelope cannot fit fails loud rather than leaving the run without a terminal.
|
|
863
|
-
*
|
|
864
|
-
* @returns the run that was closed, or `null` when the stream was already at a stopping point.
|
|
865
|
-
*/
|
|
866
|
-
closeRun(o: {
|
|
867
|
-
timestamp: number;
|
|
868
|
-
cotal?: CotalMeta;
|
|
869
|
-
/** Close with `RUN_ERROR` carrying these instead of `RUN_FINISHED`. */
|
|
870
|
-
error?: {
|
|
871
|
-
message: string;
|
|
872
|
-
code?: string;
|
|
873
|
-
};
|
|
874
|
-
}): Promise<string | null>;
|
|
875
|
-
/** Measure a candidate frame EXACTLY as the wire will, at an upper bound over id and expectation. */
|
|
876
|
-
private measure;
|
|
877
|
-
/** Transition 1 then the first network attempt. */
|
|
878
|
-
private publish;
|
|
879
|
-
/**
|
|
880
|
-
* One publish attempt — first or retry — with the FROZEN id and the FROZEN `E`. Never the tip.
|
|
881
|
-
*
|
|
882
|
-
* The three outcomes are not symmetric and the asymmetry is the design:
|
|
883
|
-
* - `!duplicate` → transition 2 then 3. Success becomes durable before the frontier moves.
|
|
884
|
-
* - `duplicate` → HALT. On a first attempt it means a body WE DID NOT WRITE holds our id, and
|
|
885
|
-
* folding its `ackSeq` would advance the frontier and the source cursor past events that were
|
|
886
|
-
* never published. On a retry it cannot happen on a single-replica stream at all, because such a
|
|
887
|
-
* stream evaluates the expectation before the dedup cache, so observing it proves the stream is
|
|
888
|
-
* not single-replica. Both are
|
|
889
|
-
* fail-loud, and neither is a case where guessing is better than stopping.
|
|
890
|
-
* - CAS loss → HALT. Someone else moved the tip on a subject only this principal may write, or
|
|
891
|
-
* the subject was purged. Uncertainty plus a moved tip is exactly what must not be guessed at.
|
|
892
|
-
*
|
|
893
|
-
* A NETWORK error is deliberately none of these: it leaves `pending` as `sent_unacked`, which is
|
|
894
|
-
* the state that means "we do not know", and the next boot retries the same frozen frame.
|
|
895
|
-
*/
|
|
896
|
-
private attempt;
|
|
897
|
-
/**
|
|
898
|
-
* Decide whether a bracket refusal is the WRITER's fault or OURS, and say which.
|
|
899
|
-
*
|
|
900
|
-
* Ours iff ALL THREE hold, and each is load-bearing:
|
|
901
|
-
* - this process has fed NO event through the machine yet, so the machine cannot have been put
|
|
902
|
-
* into a bad state by anything we did in this run; and
|
|
903
|
-
* - the frontier is non-virgin, so frames — and therefore possibly an open `RUN_STARTED` — were
|
|
904
|
-
* published by a PREVIOUS process; and
|
|
905
|
-
* - the WAL cannot say what was open. Since v2 the machine is PERSISTED, so an ordinary restart
|
|
906
|
-
* restores it and never reaches here at all; `null` means the document was migrated from v1 and
|
|
907
|
-
* genuinely never recorded the state. Without this condition the diagnosis would survive as a
|
|
908
|
-
* permanent excuse for a case the migration fixed.
|
|
909
|
-
*
|
|
910
|
-
* Drop the first condition and a genuine mid-stream violation by the writer gets blamed on a
|
|
911
|
-
* restart that happened an hour ago. Drop the second and a violation on a virgin thread, where
|
|
912
|
-
* nothing was ever published and nothing could have been lost, gets blamed on a restart that never
|
|
913
|
-
* happened. Each condition alone produces a confident, wrong diagnosis — which is worse than the
|
|
914
|
-
* undiagnosed error it replaced, because a named cause stops the search.
|
|
915
|
-
*/
|
|
916
|
-
private diagnoseBracket;
|
|
917
|
-
private halt;
|
|
918
|
-
}
|
|
919
620
|
//# sourceMappingURL=agui.d.ts.map
|
package/dist/agui.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"agui.d.ts","sourceRoot":"","sources":["../src/agui.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"agui.d.ts","sourceRoot":"","sources":["../src/agui.ts"],"names":[],"mappings":"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"}
|