fix: collapse the evidence-key gate and resolver into one decision
Three fix rounds each rebuilt the gate as a separate expression that merely agreed with the resolver on the inputs that round's tests used. Different expressions cannot agree in general, so the defect class stayed open while each reported instance closed. `findResolvableAsset(assets, key)` is now the single place that decides which Asset an evidence key resolves to. Every gate is `Boolean(findResolvableAsset(...)) || legacyKey(key)` via one shared composition, and every resolver returns what it returns: - validate-working-copy: the key gate and the decorative lookup (a last-wins Map against the resolver's first-wins find, so alt could be judged against a different Asset than the one rendered) - adapters/mock/project-public-render-model: gate and resolver - instant-preview: gate and descriptor resolver - createAssetCatalogResolver: the pixels, a fourth expression nobody had listed -- one Asset's caption could sit over another Asset's image Duplicate assetKeys are a contract violation but reachable through a paged list, so the choice is total and order-independent: newest updatedAt wins, tie-broken by id. InstantPreview's gate is no longer looser than the others. The un-loaded-asset case it was loosened for blanks either way; all the looseness bought was catalog-only keys rendering an empty gap with no message while validation said EVIDENCE_UNSUPPORTED. The test that pinned that divergence now asserts the consistent behaviour, and the false comment claiming a fix that did not exist is gone. idempotent() now maps a deterministic content failure to VALIDATION_STALE/409 instead of offering a retry that fails identically, and no longer caches uncharacterized internal failures -- reporting one as retryable while freezing it in the ledger meant the retry could never re-run. Adds tests/features/tech-log/evidence-key-agreement.test.ts: 144 adversarial (asset list, key) combinations asserting the agreement itself rather than examples. It reported 53 disagreements against the previous code. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Opus 5
parent
783e9b2cf1
commit
073fda87eb
@@ -1,50 +1,94 @@
|
||||
import type { components } from "../../contracts/studio/generated.ts";
|
||||
import type { Asset } from "../../contracts/studio/contract.ts";
|
||||
import type { SupportsEvidenceKey } from "../public-render-content.ts";
|
||||
import { evidenceCatalogEntryFor } from "./project-public-render-model.ts";
|
||||
|
||||
type CatalogEntry = components["schemas"]["CatalogEntry"];
|
||||
|
||||
/**
|
||||
* The single place that bridges the Asset system (Tasks 6/7) and the
|
||||
* document catalog `projectWorkingCopy` (Instant Preview) and
|
||||
* `validateWorkingCopy` (mock validation) gate `EVIDENCE_FIGURE` blocks
|
||||
* against. Fix round 1 (I2): both paths previously derived their own,
|
||||
* independently-written notion of "does a loaded Asset make this key
|
||||
* referenceable" -- Instant Preview learned to accept a freshly loaded
|
||||
* Asset, but the mock's validate step still only recognized the one
|
||||
* hardcoded legacy key, so a directive the Asset Picker inserted could
|
||||
* preview perfectly and then fail validation. Both paths now call this one
|
||||
* function instead.
|
||||
* An `Asset` that can actually produce pixels for an evidence key: `READY`,
|
||||
* and carrying a real `publicPath`. The narrowed `publicPath` is what lets a
|
||||
* caller build a `ResolvedAsset` without re-testing (or defaulting) the field
|
||||
* the gate already tested.
|
||||
*/
|
||||
export type ResolvableAsset = Asset & { publicPath: string };
|
||||
|
||||
/**
|
||||
* The one place that decides which `Asset` an evidence key resolves to.
|
||||
*
|
||||
* Fix round 2 (I2 regression): gate 1 ("may this document reference this key
|
||||
* at all") and gate 2 ("does some catalog actually carry it") must ask
|
||||
* different questions. Round 1 called `supportsEvidenceKeyIn(mergedCatalog)`
|
||||
* for BOTH gates, so any `EVIDENCE` catalog row backing something other than
|
||||
* an Asset (e.g. the pre-existing "Fetch Join Case" row that exists for
|
||||
* QUESTION resolution targets, not media) passed gate 1 even though no Asset
|
||||
* and no legacy key back it. Round 2 narrowed gate 1 to
|
||||
* `supportsEvidenceKeyIn(evidenceCatalogEntriesFromAssets(assets))` --
|
||||
* still `evidenceCatalogEntryFor` under the hood, matching on
|
||||
* `id || label || publicPath`.
|
||||
* Every "can this key be rendered" question is `Boolean(findResolvableAsset(...))`
|
||||
* and every "what does it render" answer is the `Asset` this returns, so the
|
||||
* two cannot disagree. Fix rounds 1-3 each rebuilt the gate as a *separate*
|
||||
* expression that merely agreed with the resolver on the inputs that round's
|
||||
* tests used -- a catalog lookup over merged rows, then over synthesized rows,
|
||||
* then `assets.some(a => P(a) && Q(a))` against a resolver doing
|
||||
* `Q(first a satisfying P)`. The last pair still disagreed whenever two
|
||||
* `READY` Assets shared one `assetKey` and the first had no `publicPath`:
|
||||
* `some` found the second, `find` returned the first, and the document
|
||||
* validated clean while the render model carried `publicPath: ""`.
|
||||
*
|
||||
* Fix round 3 (same regression, third instance): `evidenceCatalogEntryFor`
|
||||
* is gate 2's question, asked over fewer rows -- it is still not the same
|
||||
* predicate as the resolver's actual success condition (`assetKey === key &&
|
||||
* managementStatus === "READY" && Boolean(publicPath)`), so a `READY` Asset
|
||||
* with `publicPath: null`/`""`, or one whose `publicPath` happens to match
|
||||
* `/media/${someOtherKey}.svg` for a key that isn't its own `assetKey`,
|
||||
* still passed gate 1 while the resolver could not produce real pixels for
|
||||
* it. Gate 1 must therefore be built directly from
|
||||
* `supportsEvidenceKeyFromReadyAssets` below -- the resolver's own
|
||||
* condition, not a catalog lookup -- never through
|
||||
* `evidenceCatalogEntryFor`/`supportsEvidenceKeyIn`. Gate 2 keeps using the
|
||||
* merged catalog via `evidenceCatalogEntryFor` as before. See
|
||||
* `validate-working-copy.ts` and `adapters/mock/project-public-render-model.ts`
|
||||
* for the compositions; `instant-preview.tsx` deliberately keeps gate 1 on
|
||||
* the merged catalog (its resolver can never throw, so a loose gate there
|
||||
* only ever degrades to a placeholder, and a strict assets-only gate was
|
||||
* itself a regression -- see that file's comment).
|
||||
* ## Which Asset wins when several share a key
|
||||
*
|
||||
* The contract calls `assetKey` immutable and forbids reuse after publication
|
||||
* history, so two `Asset`s sharing one is a backend contract violation -- but
|
||||
* "that cannot happen" is exactly the reasoning that let this bug recur three
|
||||
* times, and a list assembled from paged `listAssets` responses can carry the
|
||||
* shape regardless. The choice made here is therefore **total** (every key
|
||||
* gets an answer) and **order-independent** (the answer does not depend on how
|
||||
* the caller happened to sort or page the array): among the resolvable
|
||||
* candidates, the most recently updated one wins, ties broken by the greater
|
||||
* `id`. Newest-wins matches what a reader expects of a re-uploaded asset;
|
||||
* `id` is a total, stable tiebreak so equal timestamps still yield one answer.
|
||||
* Plain string comparison, not `localeCompare` -- both fields are ASCII
|
||||
* (RFC 3339 timestamps, UUIDs) and must not vary with the ambient locale.
|
||||
*/
|
||||
export function findResolvableAsset(
|
||||
assets: readonly Asset[],
|
||||
key: string,
|
||||
): ResolvableAsset | undefined {
|
||||
let winner: ResolvableAsset | undefined;
|
||||
for (const asset of assets) {
|
||||
if (asset.assetKey !== key) continue;
|
||||
if (asset.managementStatus !== "READY") continue;
|
||||
if (!asset.publicPath) continue;
|
||||
const candidate = asset as ResolvableAsset;
|
||||
if (!winner || outranks(candidate, winner)) winner = candidate;
|
||||
}
|
||||
return winner;
|
||||
}
|
||||
|
||||
function outranks(candidate: ResolvableAsset, incumbent: ResolvableAsset): boolean {
|
||||
if (candidate.updatedAt !== incumbent.updatedAt) {
|
||||
return candidate.updatedAt > incumbent.updatedAt;
|
||||
}
|
||||
return candidate.id > incumbent.id;
|
||||
}
|
||||
|
||||
/**
|
||||
* The evidence-key gate every caller uses. A key is referenceable when a real
|
||||
* Asset resolves it, or when it is the caller's own legacy static key -- the
|
||||
* one key that predates the Asset gateway and is served from a hardcoded
|
||||
* registry instead. `presentation/` may not import `adapters/`, so each layer
|
||||
* passes its own copy of that predicate rather than sharing an import; the
|
||||
* composition itself lives here so it cannot drift between callers.
|
||||
*/
|
||||
export function supportsResolvableEvidenceKey(
|
||||
assets: readonly Asset[],
|
||||
isLegacyEvidenceKey: (key: string) => boolean,
|
||||
): SupportsEvidenceKey {
|
||||
return (key: string) =>
|
||||
Boolean(findResolvableAsset(assets, key)) || isLegacyEvidenceKey(key);
|
||||
}
|
||||
|
||||
/**
|
||||
* Bridges the Asset system into the document catalog the projection's
|
||||
* *catalog* check (a separate question: "does some catalog carry a row for
|
||||
* this key at all") reads. Only `READY` Assets synthesize a row, so an asset
|
||||
* under review never makes a key referenceable.
|
||||
*
|
||||
* `id` is deliberately not `asset.id`: the catalog check also matches on `id`,
|
||||
* so reusing the real Asset UUID would let anyone who has seen it elsewhere
|
||||
* type it directly as a directive key. Prefixed so it can never collide with
|
||||
* a real `asset.id`.
|
||||
*/
|
||||
export function evidenceCatalogEntriesFromAssets(
|
||||
assets: readonly Asset[],
|
||||
@@ -52,13 +96,6 @@ export function evidenceCatalogEntriesFromAssets(
|
||||
return assets
|
||||
.filter((asset) => asset.managementStatus === "READY")
|
||||
.map((asset) => ({
|
||||
// Not `asset.id` (fix round 2): `evidenceCatalogEntryFor` also matches
|
||||
// on `id`, so reusing the real Asset UUID here would let anyone who
|
||||
// has seen that UUID elsewhere (an API response, an admin view) type
|
||||
// it directly as a directive key and have it resolve — a path the
|
||||
// Picker never produces (it always emits `assetKey`) and that widens
|
||||
// the reference surface for no benefit. Prefixed so it can never
|
||||
// collide with a real `asset.id` a caller might paste in.
|
||||
id: `asset-evidence:${asset.id}`,
|
||||
type: "EVIDENCE",
|
||||
label: asset.assetKey,
|
||||
@@ -66,44 +103,3 @@ export function evidenceCatalogEntriesFromAssets(
|
||||
dependencyRevision: asset.updatedAt,
|
||||
}));
|
||||
}
|
||||
|
||||
/**
|
||||
* `SupportsEvidenceKey` built from the same rule the catalog-entry gate
|
||||
* uses. Deliberately kept -- `instant-preview.tsx`'s gate 1 still uses this
|
||||
* over the merged catalog on purpose (see that file), but fix round 3
|
||||
* removed it from `validate-working-copy.ts` and
|
||||
* `adapters/mock/project-public-render-model.ts`'s gate 1: it answers gate
|
||||
* 2's question, not "can a real Asset resolve this key", and reusing it for
|
||||
* gate 1 is what let this bug recur twice.
|
||||
*/
|
||||
export function supportsEvidenceKeyIn(
|
||||
catalog: ReadonlyArray<CatalogEntry>,
|
||||
): SupportsEvidenceKey {
|
||||
return (key: string) => Boolean(evidenceCatalogEntryFor(catalog, key));
|
||||
}
|
||||
|
||||
/**
|
||||
* Fix round 3. The resolver's own success condition, extracted so gate 1 can
|
||||
* be built from the *exact* predicate that decides whether a key actually
|
||||
* produces pixels, instead of a catalog lookup that can diverge from it
|
||||
* (`evidenceCatalogEntryFor` matches on `id || label || publicPath` against
|
||||
* whatever `evidenceCatalogEntriesFromAssets` happened to synthesize, which
|
||||
* is not the same expression as "does some `READY` Asset's own `assetKey`
|
||||
* equal this key and does it have real `publicPath`"). Two shapes where they
|
||||
* disagreed: a `READY` Asset with `publicPath: null`/`""`, and a `READY`
|
||||
* Asset whose `publicPath` happens to satisfy the legacy
|
||||
* `/media/${someOtherKey}.svg` convention for a key that is not its own
|
||||
* `assetKey`. Both passed the catalog-based gate while the resolver could
|
||||
* not produce a real descriptor for them.
|
||||
*/
|
||||
export function supportsEvidenceKeyFromReadyAssets(
|
||||
assets: readonly Asset[],
|
||||
): SupportsEvidenceKey {
|
||||
return (key: string) =>
|
||||
assets.some(
|
||||
(asset) =>
|
||||
asset.assetKey === key &&
|
||||
asset.managementStatus === "READY" &&
|
||||
Boolean(asset.publicPath),
|
||||
);
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user