@@ -30,7 +30,7 @@ import { Buffer } from "node:buffer";
3030import type { Operation } from "effection" ;
3131import { prepareElicitation , validateParsed } from "@executablemd/core" ;
3232import { parseDurableEvent } from "@executablemd/durable-streams" ;
33- import type { DurableEvent , Json } from "@executablemd/durable-streams" ;
33+ import type { DurableEvent , EffectDescription , Json , Result } from "@executablemd/durable-streams" ;
3434import { SUSPENSION_ANSWER } from "../../suspension/answer.ts" ;
3535import {
3636 parseSuspensionRequest ,
@@ -1408,48 +1408,85 @@ function verifyCheckouts(contents: XmdArtifactContents, reject: Reject): void {
14081408 }
14091409}
14101410
1411+ /** One retained Yield, at the durable position its coroutine gave it. */
1412+ interface DurableYield {
1413+ readonly eventId : string ;
1414+ readonly coroutineId : string ;
1415+ /** The count of settled yields this coroutine had before this one. */
1416+ readonly index : number ;
1417+ readonly description : EffectDescription ;
1418+ readonly result : Result ;
1419+ }
1420+
1421+ /** One published answer, and where in its coroutine it was published. */
1422+ interface AnswerPublication {
1423+ readonly suspensionId : string ;
1424+ readonly at : DurableYield ;
1425+ }
1426+
14111427/**
14121428 * Every retained answer, authenticated against the history it claims to answer.
14131429 *
1414- * A row naming an event the journal holds proves nothing on its own: what has
1430+ * A row naming an event the journal holds proves nothing on its own. What has
14151431 * to be true is that the named event *is* the wait, that it is *this* wait, that
14161432 * the request it retained is the one the value was judged against, that the
1417- * value could still end that wait, and that the row's state agrees with whether
1418- * the journal published an answer for it.
1433+ * value could still end that wait, and — when the row says the wait is over —
1434+ * that the journal published exactly that value at exactly the position a
1435+ * publication occupies.
1436+ *
1437+ * That last part is a position, not an ordering. `suspendFor()` publishes the
1438+ * request and then the answer as two durable operations in one coroutine, back
1439+ * to back, so an answer sits at the request's index plus one *in that
1440+ * coroutine*. Accepting any later row anywhere in the journal would accept a
1441+ * publication belonging to some other wait, in some other coroutine, as
1442+ * evidence that this one ended.
14191443 *
1420- * Every one of those questions is asked with the live contracts rather than
1421- * with an encoding of this module's own — the same `parseSuspensionRequest`,
1422- * the same fingerprint, the same schema compilation a delivery and a resume
1423- * use. A second spelling of any of them would be a second answer to a question
1424- * a live run has already settled.
1444+ * Every question is asked with the live contracts rather than with an encoding
1445+ * of this module's own — the same `parseSuspensionRequest`, the same
1446+ * fingerprint, the same schema compilation a delivery and a resume use. A
1447+ * second spelling of any of them would be a second answer to a question a live
1448+ * run has already settled.
14251449 */
14261450function * verifySuspensions (
14271451 contents : XmdArtifactContents ,
14281452 path : string ,
14291453 reject : Reject ,
14301454) : Operation < void > {
1431- const journal = contents . journal . map ( ( row ) => ( {
1432- eventId : row . eventId ,
1433- event : parseJournalEvent ( row . record , path ) ,
1434- } ) ) ;
1435- const requests = new Map < string , { readonly at : number ; readonly event : DurableEvent } > ( ) ;
1436- const publications = new Map < string , number > ( ) ;
1437-
1438- for ( const [ at , entry ] of journal . entries ( ) ) {
1439- const event = entry . event ;
1440- if ( event . type !== "yield" ) {
1455+ const yields = durableYields ( contents , path ) ;
1456+ const requests = new Map < string , DurableYield > ( ) ;
1457+ const byPosition = new Map < string , DurableYield > ( ) ;
1458+ const published = new Map < string , AnswerPublication > ( ) ;
1459+
1460+ for ( const entry of yields ) {
1461+ byPosition . set ( positionKey ( entry . coroutineId , entry . index ) , entry ) ;
1462+ if ( entry . description . type === SUSPENSION_REQUEST ) {
1463+ requests . set ( entry . eventId , entry ) ;
1464+ }
1465+ }
1466+
1467+ for ( const entry of yields ) {
1468+ if ( entry . description . type !== SUSPENSION_ANSWER ) {
14411469 continue ;
14421470 }
1443- if ( event . description . type === SUSPENSION_REQUEST ) {
1444- requests . set ( entry . eventId , { at, event } ) ;
1471+ const named = entry . description [ "name" ] ;
1472+ if ( typeof named !== "string" || named !== entry . description [ "suspensionId" ] ) {
1473+ reject ( "a published answer does not name one wait" ) ;
14451474 }
1446- if ( event . description . type === SUSPENSION_ANSWER ) {
1447- const named = event . description . name ;
1448- if ( typeof named !== "string" || publications . has ( named ) ) {
1449- reject ( "it publishes more than one answer for one wait" ) ;
1450- }
1451- publications . set ( named , at ) ;
1475+ if ( published . has ( named ) ) {
1476+ reject ( "it publishes more than one answer for one wait" ) ;
14521477 }
1478+ // Structural, and asked of every publication whether or not a row claims
1479+ // it: an answer is published directly behind the request it answers, so one
1480+ // standing anywhere else answers nothing this artifact holds.
1481+ const behind = byPosition . get ( positionKey ( entry . coroutineId , entry . index - 1 ) ) ;
1482+ if (
1483+ behind === undefined ||
1484+ behind . description . type !== SUSPENSION_REQUEST ||
1485+ behind . description [ "name" ] !== named
1486+ ) {
1487+ reject ( "an answer is published somewhere other than behind the request it answers" ) ;
1488+ }
1489+ published . set ( named , Object . freeze ( { suspensionId : named , at : entry } ) ) ;
14531490 }
14541491
14551492 const suspensions = new Set < string > ( ) ;
@@ -1463,13 +1500,9 @@ function* verifySuspensions(
14631500 if ( request === undefined ) {
14641501 reject ( "a suspension answer names an event that is not a retained request for a wait" ) ;
14651502 }
1466- const description = request . event . type === "yield" ? request . event . description : undefined ;
1467- if ( description === undefined ) {
1468- reject ( "a suspension answer names an event that is not a retained request for a wait" ) ;
1469- }
14701503 if (
1471- description [ "name" ] !== answer . suspensionId ||
1472- description [ "suspensionId" ] !== answer . suspensionId
1504+ request . description [ "name" ] !== answer . suspensionId ||
1505+ request . description [ "suspensionId" ] !== answer . suspensionId
14731506 ) {
14741507 reject ( "a suspension answer names a request published for a different wait" ) ;
14751508 }
@@ -1481,8 +1514,8 @@ function* verifySuspensions(
14811514 let wait : WorkflowSuspensionRequest ;
14821515 try {
14831516 wait = parseSuspensionRequest ( {
1484- request : description [ "request" ] ,
1485- responseSchema : description [ "responseSchema" ] ,
1517+ request : request . description [ "request" ] ,
1518+ responseSchema : request . description [ "responseSchema" ] ,
14861519 } ) ;
14871520 } catch {
14881521 // The live parser's sentence describes a request a document offered; what
@@ -1495,23 +1528,65 @@ function* verifySuspensions(
14951528 }
14961529 yield * judgeRetainedAnswer ( wait , answer . answer , reject ) ;
14971530
1498- const publishedAt = publications . get ( answer . suspensionId ) ;
1499- if ( answer . state === "consumed" && publishedAt === undefined ) {
1531+ const publication = published . get ( answer . suspensionId ) ;
1532+ if ( answer . state === "pending" ) {
1533+ if ( publication !== undefined ) {
1534+ reject ( "a pending suspension answer was already published in this artifact's history" ) ;
1535+ }
1536+ continue ;
1537+ }
1538+ if ( publication === undefined ) {
15001539 reject ( "a consumed suspension answer has no published answer in this artifact's history" ) ;
15011540 }
1502- if ( answer . state === "pending" && publishedAt !== undefined ) {
1503- reject ( "a pending suspension answer was already published in this artifact's history" ) ;
1541+ if (
1542+ publication . at . coroutineId !== request . coroutineId ||
1543+ publication . at . index !== request . index + 1
1544+ ) {
1545+ reject ( "a consumed suspension answer was published away from the wait it ended" ) ;
1546+ }
1547+ if ( publication . at . result . status !== "ok" ) {
1548+ reject ( "a consumed suspension answer was published without a value that ended the wait" ) ;
15041549 }
1505- if ( publishedAt !== undefined && publishedAt <= request . at ) {
1506- reject ( "a suspension answer is published before the request it answers" ) ;
1550+ if (
1551+ canonicalJsonText ( publication . at . result . value ?? null ) !== canonicalJsonText ( answer . answer )
1552+ ) {
1553+ reject ( "a consumed suspension answer was published carrying a different value" ) ;
15071554 }
15081555 }
1556+ }
1557+
1558+ function positionKey ( coroutineId : string , index : number ) : string {
1559+ return `${ JSON . stringify ( coroutineId ) } ${ index } ` ;
1560+ }
15091561
1510- for ( const suspension of publications . keys ( ) ) {
1511- if ( ! suspensions . has ( suspension ) ) {
1512- reject ( "it publishes an answer for a wait it retains no answer for" ) ;
1562+ /**
1563+ * Every retained Yield, with the durable position its coroutine gave it.
1564+ *
1565+ * A position is a count of that coroutine's settled yields, so it is recovered
1566+ * by counting them in append order. A Close terminates a coroutine and settles
1567+ * no operation, so it occupies no position and is not counted.
1568+ */
1569+ function durableYields ( contents : XmdArtifactContents , path : string ) : readonly DurableYield [ ] {
1570+ const counts = new Map < string , number > ( ) ;
1571+ const entries : DurableYield [ ] = [ ] ;
1572+ for ( const row of contents . journal ) {
1573+ const event = parseJournalEvent ( row . record , path ) ;
1574+ if ( event . type !== "yield" ) {
1575+ continue ;
15131576 }
1577+ const index = counts . get ( event . coroutineId ) ?? 0 ;
1578+ counts . set ( event . coroutineId , index + 1 ) ;
1579+ entries . push (
1580+ Object . freeze ( {
1581+ eventId : row . eventId ,
1582+ coroutineId : event . coroutineId ,
1583+ index,
1584+ description : event . description ,
1585+ result : event . result ,
1586+ } ) ,
1587+ ) ;
15141588 }
1589+ return Object . freeze ( entries ) ;
15151590}
15161591
15171592/**
0 commit comments