@milaboratories/pl-client 3.17.6 → 3.18.0

package/dist/core/final.cjs

@@ -1,80 +1,215 @@
 const require_types = require("./types.cjs");
+const require_finality = require("./finality.cjs");
 let _milaboratories_pl_model_common = require("@milaboratories/pl-model-common");
 //#region src/core/final.ts
-function readyOrDuplicateOrError(r) {
-	return r.resourceReady || require_types.isNotNullSignedResourceId(r.originalResourceId) || require_types.isNotNullSignedResourceId(r.error);
-}
-function readyAndHasAllOutputsFilled(r) {
-	if (!readyOrDuplicateOrError(r)) return false;
-	if (!r.outputsLocked) return false;
-	if (r.fields === void 0) return true;
-	for (const f of r.fields) if (require_types.isNullSignedResourceId(f.error) && (require_types.isNullSignedResourceId(f.value) || !f.valueIsFinal)) return false;
-	return true;
-}
-const unknownResourceTypeNames = /* @__PURE__ */ new Set();
-/** Default implementation, defining behaviour for built-in resource types. */
-const DefaultFinalResourceDataPredicate = (r) => {
-	switch (r.type.name) {
-		case _milaboratories_pl_model_common.ResourceTypeName.StreamManager: {
-			if (!readyOrDuplicateOrError(r)) return false;
-			if (r.fields === void 0) return true;
-			if (require_types.isNotNullSignedResourceId(r.error)) return true;
-			const downloadable = require_types.getField(r, "downloadable");
-			return require_types.getField(r, "stream").value === downloadable.value;
+const earlyOnFieldErrors = {
+	approx: "readyOrDuplicateOrError",
+	reason: "HAS_ERRORS is set by an error on any field, the predicate reads the resource error only; an early stop is followed up with a plain fetch"
+};
+const earlyOnFieldErrorsWithOutputs = {
+	approx: "readyAndAllOutputsFilled",
+	reason: "HAS_ERRORS is set by an error on any field, the predicate reads the resource error only; ALL_OUTPUTS_FINAL, like the predicate, checks every retained field; an early stop is followed up with a plain fetch"
+};
+const value = (name) => ({
+	match: { name },
+	rule: "always",
+	why: "a value, written once at creation"
+});
+const settledAtReady = (name, why) => ({
+	match: { name },
+	rule: "readyOrDuplicateOrError",
+	why,
+	stopRule: earlyOnFieldErrors
+});
+const never = (match, why) => ({
+	match,
+	rule: "never",
+	why
+});
+/** The base layer: nothing observable (state, fields, KV) changes after the rule holds, whatever
+* the consumer prunes. Exceptions: the data-loss error cascade, the `hasOriginalListeners` flag,
+* and the writes its entries name. */
+const StrictFinality = require_finality.FinalityTable.of("strict", [
+	value(_milaboratories_pl_model_common.ResourceTypeName.JsonObject),
+	value(_milaboratories_pl_model_common.ResourceTypeName.JsonGzObject),
+	value(_milaboratories_pl_model_common.ResourceTypeName.JsonString),
+	value(_milaboratories_pl_model_common.ResourceTypeName.JsonArray),
+	value(_milaboratories_pl_model_common.ResourceTypeName.JsonNumber),
+	value(_milaboratories_pl_model_common.ResourceTypeName.JsonBool),
+	value(_milaboratories_pl_model_common.ResourceTypeName.JsonNull),
+	{
+		match: { name: _milaboratories_pl_model_common.ResourceTypeName.JsonErrorTrace },
+		rule: "always",
+		why: "an error-trace snapshot, populated and locked in its creating transaction"
+	},
+	value(_milaboratories_pl_model_common.ResourceTypeName.BContextEnd),
+	value(_milaboratories_pl_model_common.ResourceTypeName.FrontendFromUrl),
+	value(_milaboratories_pl_model_common.ResourceTypeName.FrontendFromFolder),
+	value(_milaboratories_pl_model_common.ResourceTypeName.FrontendFromLocalTgz),
+	value(_milaboratories_pl_model_common.ResourceTypeName.BObjectSpec),
+	value(_milaboratories_pl_model_common.ResourceTypeName.Null),
+	value(_milaboratories_pl_model_common.ResourceTypeName.Binary),
+	{
+		match: { name: _milaboratories_pl_model_common.ResourceTypeName.JsonResourceError },
+		rule: { custom: (r) => r.type.version === "1" },
+		why: "version 1 is a value, written once at creation",
+		stopRule: {
+			approx: "always",
+			reason: "a stop rule cannot see the type version"
 		}
-		case _milaboratories_pl_model_common.ResourceTypeName.StdMap:
-		case _milaboratories_pl_model_common.ResourceTypeName.StdMapSlash:
-		case _milaboratories_pl_model_common.ResourceTypeName.EphStdMap:
-		case _milaboratories_pl_model_common.ResourceTypeName.PFrame:
-		case _milaboratories_pl_model_common.ResourceTypeName.ParquetChunk:
-		case _milaboratories_pl_model_common.ResourceTypeName.BContext:
-		case _milaboratories_pl_model_common.ResourceTypeName.BlockPackCustom:
-		case _milaboratories_pl_model_common.ResourceTypeName.BinaryMap:
-		case _milaboratories_pl_model_common.ResourceTypeName.BinaryValue:
-		case _milaboratories_pl_model_common.ResourceTypeName.BlobMap:
-		case _milaboratories_pl_model_common.ResourceTypeName.BResolveSingle:
-		case _milaboratories_pl_model_common.ResourceTypeName.BResolveSingleNoResult:
-		case _milaboratories_pl_model_common.ResourceTypeName.BQueryResult:
-		case _milaboratories_pl_model_common.ResourceTypeName.TengoTemplate:
-		case _milaboratories_pl_model_common.ResourceTypeName.TengoLib:
-		case _milaboratories_pl_model_common.ResourceTypeName.SoftwareInfo:
-		case _milaboratories_pl_model_common.ResourceTypeName.Dummy: return readyOrDuplicateOrError(r);
-		case _milaboratories_pl_model_common.ResourceTypeName.JsonResourceError: return r.type.version === "1";
-		case _milaboratories_pl_model_common.ResourceTypeName.JsonObject:
-		case _milaboratories_pl_model_common.ResourceTypeName.JsonGzObject:
-		case _milaboratories_pl_model_common.ResourceTypeName.JsonString:
-		case _milaboratories_pl_model_common.ResourceTypeName.JsonArray:
-		case _milaboratories_pl_model_common.ResourceTypeName.JsonNumber:
-		case _milaboratories_pl_model_common.ResourceTypeName.BContextEnd:
-		case _milaboratories_pl_model_common.ResourceTypeName.FrontendFromUrl:
-		case _milaboratories_pl_model_common.ResourceTypeName.FrontendFromFolder:
-		case _milaboratories_pl_model_common.ResourceTypeName.BObjectSpec:
-		case _milaboratories_pl_model_common.ResourceTypeName.Blob:
-		case _milaboratories_pl_model_common.ResourceTypeName.Null:
-		case _milaboratories_pl_model_common.ResourceTypeName.Binary:
-		case _milaboratories_pl_model_common.ResourceTypeName.LSProvider:
-		case _milaboratories_pl_model_common.ResourceTypeName.WorkingDirectory: return true;
-		case _milaboratories_pl_model_common.ResourceTypeName.UserProject:
-		case _milaboratories_pl_model_common.ResourceTypeName.Projects:
-		case _milaboratories_pl_model_common.ResourceTypeName.ClientRoot:
-		case _milaboratories_pl_model_common.ResourceTypeName.SharingOutbox:
-		case _milaboratories_pl_model_common.ResourceTypeName.SharingState:
-		case _milaboratories_pl_model_common.ResourceTypeName.SharedEnvelope: return false;
-		default: if (r.type.name.startsWith(_milaboratories_pl_model_common.ResourceTypePrefix.Blob) || r.type.name.startsWith(_milaboratories_pl_model_common.ResourceTypePrefix.LS) || r.type.name.startsWith(_milaboratories_pl_model_common.ResourceTypePrefix.WorkingDirectory) || r.type.name.startsWith(_milaboratories_pl_model_common.ResourceTypePrefix.StorageSpaceAllocation)) return true;
-		else if (r.type.name.startsWith(_milaboratories_pl_model_common.ResourceTypePrefix.BlobUpload) || r.type.name.startsWith(_milaboratories_pl_model_common.ResourceTypePrefix.BlobIndex)) return readyAndHasAllOutputsFilled(r);
-		else if (r.type.name.startsWith(_milaboratories_pl_model_common.ResourceTypePrefix.PColumnData)) return readyOrDuplicateOrError(r);
-		else if (r.type.name.startsWith(_milaboratories_pl_model_common.ResourceTypePrefix.StreamWorkdir)) return readyOrDuplicateOrError(r);
-		else if (!unknownResourceTypeNames.has(r.type.name)) {
-			console.log("UNKNOWN RESOURCE TYPE: " + r.type.name);
-			unknownResourceTypeNames.add(r.type.name);
+	},
+	{
+		match: { prefix: _milaboratories_pl_model_common.ResourceTypePrefix.LS },
+		rule: "always",
+		why: "no write after creation"
+	},
+	{
+		match: { prefix: _milaboratories_pl_model_common.ResourceTypePrefix.WorkingDirectory },
+		rule: "always",
+		why: "no write after creation"
+	},
+	{
+		match: { prefix: _milaboratories_pl_model_common.ResourceTypePrefix.StorageSpaceAllocation },
+		rule: "always",
+		why: "no write after creation"
+	},
+	...[
+		_milaboratories_pl_model_common.ResourceTypeName.StdMap,
+		_milaboratories_pl_model_common.ResourceTypeName.StdMapSlash,
+		_milaboratories_pl_model_common.ResourceTypeName.EphStdMap,
+		_milaboratories_pl_model_common.ResourceTypeName.PFrame,
+		_milaboratories_pl_model_common.ResourceTypeName.ParquetChunk,
+		_milaboratories_pl_model_common.ResourceTypeName.BContext,
+		_milaboratories_pl_model_common.ResourceTypeName.BinaryMap,
+		_milaboratories_pl_model_common.ResourceTypeName.BinaryValue,
+		_milaboratories_pl_model_common.ResourceTypeName.BlobMap,
+		_milaboratories_pl_model_common.ResourceTypeName.BResolveSingleNoResult,
+		_milaboratories_pl_model_common.ResourceTypeName.BQueryResult,
+		_milaboratories_pl_model_common.ResourceTypeName.TengoLib
+	].map((name) => settledAtReady(name, "its inputs are final at ready, and no controller fills it afterwards")),
+	...[
+		_milaboratories_pl_model_common.ResourceTypeName.TengoTemplate,
+		_milaboratories_pl_model_common.ResourceTypeName.SoftwareInfo,
+		_milaboratories_pl_model_common.ResourceTypeName.BlockPackCustom
+	].map((name) => settledAtReady(name, "its only later write is the `hasOriginalListeners` flag its first duplicate sets")),
+	settledAtReady(_milaboratories_pl_model_common.ResourceTypeName.Dummy, "its only later write is a data-loss error from the Blob whose incarnation field holds it"),
+	{
+		match: { prefix: _milaboratories_pl_model_common.ResourceTypePrefix.PColumnData },
+		rule: "readyOrDuplicateOrError",
+		why: "its inputs are final at ready, and no controller fills it afterwards",
+		stopRule: earlyOnFieldErrors
+	},
+	{
+		match: { prefix: _milaboratories_pl_model_common.ResourceTypePrefix.StreamWorkdir },
+		rule: "readyOrDuplicateOrError",
+		why: "no write after ready",
+		stopRule: {
+			approx: "readyOrDuplicateOrError",
+			reason: "HAS_ERRORS is set by an error on any field; on ResourceTree walks the project field filter also removes every field, `resourceError` included, before decoding, so the predicate cannot see an error the filter stops on; an early stop is followed up with a plain fetch"
 		}
+	},
+	{
+		match: { name: _milaboratories_pl_model_common.ResourceTypeName.BResolveSingle },
+		rule: "readyAndAllOutputsFilled",
+		why: "outputs are locked at creation and assigned after ready, never overwritten; one exception: a later context with more than one match sets an error on a resolver that already succeeded, and a reader holding it final misses that error",
+		stopRule: earlyOnFieldErrorsWithOutputs
+	},
+	{
+		match: { name: _milaboratories_pl_model_common.ResourceTypeName.BResolveChoice },
+		rule: "readyAndAllOutputsFilled",
+		why: "outputs are locked at creation and point at result maps that are completed and locked as resolution finishes",
+		stopRule: earlyOnFieldErrorsWithOutputs
+	},
+	never({ name: _milaboratories_pl_model_common.ResourceTypeName.UserProject }, "blocks and fields come and go over its life"),
+	never({ name: _milaboratories_pl_model_common.ResourceTypeName.Projects }, "projects are added and removed"),
+	never({ name: _milaboratories_pl_model_common.ResourceTypeName.ClientRoot }, "its fields are added and removed"),
+	...[
+		_milaboratories_pl_model_common.ResourceTypeName.SharingOutbox,
+		_milaboratories_pl_model_common.ResourceTypeName.SharingState,
+		_milaboratories_pl_model_common.ResourceTypeName.SharedEnvelope
+	].map((name) => never({ name }, "gains and loses dynamic child fields over its life")),
+	never({ name: _milaboratories_pl_model_common.ResourceTypeName.LSProvider }, "its storage fields are rewritten on a controller restart with a changed storage config"),
+	never({ name: _milaboratories_pl_model_common.ResourceTypeName.Blob }, "its incarnation field is attached or replaced later"),
+	never({ name: _milaboratories_pl_model_common.ResourceTypeName.StreamManager }, "`stream` is reset after an error"),
+	never({ prefix: _milaboratories_pl_model_common.ResourceTypePrefix.Blob }, "its `ctl/file/blobInfo` KV is re-pointed later"),
+	never({ prefix: _milaboratories_pl_model_common.ResourceTypePrefix.BlobIndex }, "a controller restart writes its `ctl/ctlsdk/bootstrapDone` KV"),
+	never({ prefix: _milaboratories_pl_model_common.ResourceTypePrefix.BlobUpload }, "the Reset RPC deletes its `ctl/file/storage/uploadState` KV"),
+	never({ prefix: _milaboratories_pl_model_common.ResourceTypePrefix.BlobCopy }, "a controller bootstrap records its `ctl/ctlsdk/bootstrapDone` KV in a separate transaction, which may run after the copy settled"),
+	never({ name: _milaboratories_pl_model_common.ResourceTypeName.WorkingDirectory }, "lock acquisition can write its `internal/locks/lockedBy` KV after creation")
+]);
+/** What the transaction resource cache may keep while an entry stays in its LRU. The cache holds
+* state and fields, never KV, so it adds the types whose only later writes are KV. */
+const CacheFinality = StrictFinality.extend("cache", [
+	{
+		match: { prefix: _milaboratories_pl_model_common.ResourceTypePrefix.Blob },
+		rule: "always",
+		why: "`ctl/file/blobInfo` is re-pointed for the same content: the cache holds no KV, and a tree reads only its `sizeBytes`, invariant for the same content"
+	},
+	{
+		match: { prefix: _milaboratories_pl_model_common.ResourceTypePrefix.BlobIndex },
+		rule: "readyAndAllOutputsFilled",
+		why: "`ctl/ctlsdk/bootstrapDone` is backend bookkeeping KV; no client reads it",
+		stopRule: earlyOnFieldErrorsWithOutputs
+	},
+	{
+		match: { prefix: _milaboratories_pl_model_common.ResourceTypePrefix.BlobUpload },
+		rule: "readyAndAllOutputsFilled",
+		why: "`ctl/file/storage/uploadState` is backend bookkeeping KV; no client reads it",
+		stopRule: earlyOnFieldErrorsWithOutputs
+	},
+	{
+		match: { prefix: _milaboratories_pl_model_common.ResourceTypePrefix.BlobCopy },
+		rule: "readyAndAllOutputsFilled",
+		why: "outputs are locked at creation; the only later write, the bootstrap's `ctl/ctlsdk/bootstrapDone`, is backend bookkeeping KV; no client reads it",
+		stopRule: earlyOnFieldErrorsWithOutputs
+	},
+	{
+		match: { name: _milaboratories_pl_model_common.ResourceTypeName.WorkingDirectory },
+		rule: "always",
+		why: "the lock KV is backend bookkeeping; no client reads it"
 	}
-	return false;
-};
+]);
+function streamSwitchedOrErrored(r) {
+	if (!require_finality.readyOrDuplicateOrError(r)) return false;
+	if (r.fields === void 0) return true;
+	if (require_types.isNotNullSignedResourceId(r.error)) return true;
+	const downloadable = r.fields.find((f) => f.name === "downloadable");
+	const stream = r.fields.find((f) => f.name === "stream");
+	if (downloadable === void 0 || stream === void 0 || require_types.isNullSignedResourceId(stream.value)) return false;
+	return stream.value === downloadable.value;
+}
+/**
+* The finality of trees, and the default of `PlClient.finalPredicate`: a resource it calls final
+* leaves the refresh seeds, later bodies for it are ignored, and its mutable-state change sources
+* are retired. It adds Blob and StreamManager under reader assumptions stated at each entry; a
+* consumer that reads what they exclude passes its own predicate.
+*/
+const TreeFinality = CacheFinality.extend("tree", [{
+	match: { name: _milaboratories_pl_model_common.ResourceTypeName.Blob },
+	rule: "always",
+	why: "the incarnation field is replaced later; the project tree prunes Blob's fields, and the drivers read a blob by id, never through its fields",
+	requiresPruning: {
+		type: _milaboratories_pl_model_common.ResourceTypeName.Blob,
+		fields: "all"
+	}
+}, {
+	match: { name: _milaboratories_pl_model_common.ResourceTypeName.StreamManager },
+	rule: { custom: streamSwitchedOrErrored },
+	why: "after an error `stream` is reset in a later transaction; default traversal raises the error before exposing the fields, so only an `ignoreError` read sees `stream`",
+	stopRule: {
+		approx: "readyOrDuplicateOrError",
+		reason: "a stop rule cannot compare two fields, so it stops before `stream` switches"
+	}
+}]);
+/** @deprecated use {@link TreeFinality} */
+const DefaultFinalResourceDataPredicate = TreeFinality.predicate();
 //#endregion
+exports.CacheFinality = CacheFinality;
 exports.DefaultFinalResourceDataPredicate = DefaultFinalResourceDataPredicate;
 exports.ResourceTypeName = _milaboratories_pl_model_common.ResourceTypeName;
 exports.ResourceTypePrefix = _milaboratories_pl_model_common.ResourceTypePrefix;
-exports.readyOrDuplicateOrError = readyOrDuplicateOrError;
+exports.StrictFinality = StrictFinality;
+exports.TreeFinality = TreeFinality;
+exports.readyOrDuplicateOrError = require_finality.readyOrDuplicateOrError;
 
 //# sourceMappingURL=final.cjs.map

package/dist/core/final.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"final.cjs","names":["isNotNullSignedResourceId","isNullSignedResourceId","ResourceTypeName","getField","ResourceTypePrefix"],"sources":["../../src/core/final.ts"],"sourcesContent":["import type { Optional } from \"utility-types\";\nimport type { BasicResourceData, ResourceData } from \"./types\";\nimport { getField, isNotNullSignedResourceId, isNullSignedResourceId } from \"./types\";\nimport { ResourceTypeName, ResourceTypePrefix } from \"@milaboratories/pl-model-common\";\nexport { ResourceTypeName, ResourceTypePrefix };\n\n/**\n * Function is used to guide multiple layers of caching in pl-client and derived pl-tree.\n *\n * This function defines expected resource-specific state mutation behaviour,\n * if it returns true, system will expect that this data will never change as long as resource exist.\n *\n * If resource data contain information about fields, if should be taken into account, fields are undefined,\n * \"final\" state should be calculated for \"basic\" part of resource data only.\n */\nexport type FinalResourceDataPredicate = (\n  resourceData: Optional<ResourceData, \"fields\">,\n) => boolean;\n\nexport function readyOrDuplicateOrError(r: ResourceData | BasicResourceData): boolean {\n  return (\n    r.resourceReady ||\n    isNotNullSignedResourceId(r.originalResourceId) ||\n    isNotNullSignedResourceId(r.error)\n  );\n}\n\nfunction readyAndHasAllOutputsFilled(r: Optional<ResourceData, \"fields\">): boolean {\n  if (!readyOrDuplicateOrError(r)) return false;\n  if (!r.outputsLocked) return false;\n  if (r.fields === undefined) return true; // if fields are not provided basic resource state is not expected to change in the future\n  for (const f of r.fields)\n    if (isNullSignedResourceId(f.error) && (isNullSignedResourceId(f.value) || !f.valueIsFinal))\n      return false;\n  return true;\n}\n\n// solely for logging\nconst unknownResourceTypeNames = new Set<string>();\n\n/** Default implementation, defining behaviour for built-in resource types. */\nexport const DefaultFinalResourceDataPredicate: FinalResourceDataPredicate = (r): boolean => {\n  switch (r.type.name) {\n    case ResourceTypeName.StreamManager: {\n      if (!readyOrDuplicateOrError(r)) return false;\n      if (r.fields === undefined) return true; // if fields are not provided basic resource state is not expected to change in the future\n      if (isNotNullSignedResourceId(r.error)) return true;\n      const downloadable = getField(r as ResourceData, \"downloadable\");\n      const stream = getField(r as ResourceData, \"stream\");\n      return stream.value === downloadable.value; // it's equal to the resource is marked as final on backend side\n    }\n    case ResourceTypeName.StdMap:\n    case ResourceTypeName.StdMapSlash:\n    case ResourceTypeName.EphStdMap:\n    case ResourceTypeName.PFrame:\n    case ResourceTypeName.ParquetChunk:\n    case ResourceTypeName.BContext:\n    case ResourceTypeName.BlockPackCustom:\n    case ResourceTypeName.BinaryMap:\n    case ResourceTypeName.BinaryValue:\n    case ResourceTypeName.BlobMap:\n    case ResourceTypeName.BResolveSingle:\n    case ResourceTypeName.BResolveSingleNoResult:\n    case ResourceTypeName.BQueryResult:\n    case ResourceTypeName.TengoTemplate:\n    case ResourceTypeName.TengoLib:\n    case ResourceTypeName.SoftwareInfo:\n    case ResourceTypeName.Dummy:\n      return readyOrDuplicateOrError(r);\n    case ResourceTypeName.JsonResourceError:\n      return r.type.version === \"1\";\n    case ResourceTypeName.JsonObject:\n    case ResourceTypeName.JsonGzObject:\n    case ResourceTypeName.JsonString:\n    case ResourceTypeName.JsonArray:\n    case ResourceTypeName.JsonNumber:\n    case ResourceTypeName.BContextEnd:\n    case ResourceTypeName.FrontendFromUrl:\n    case ResourceTypeName.FrontendFromFolder:\n    case ResourceTypeName.BObjectSpec:\n    case ResourceTypeName.Blob:\n    case ResourceTypeName.Null:\n    case ResourceTypeName.Binary:\n    case ResourceTypeName.LSProvider:\n    case ResourceTypeName.WorkingDirectory:\n      return true;\n    case ResourceTypeName.UserProject:\n    case ResourceTypeName.Projects:\n    case ResourceTypeName.ClientRoot:\n    // Never final — these sharing resources gain and lose dynamic child fields over their lifetime.\n    case ResourceTypeName.SharingOutbox:\n    case ResourceTypeName.SharingState:\n    case ResourceTypeName.SharedEnvelope:\n      return false;\n    default:\n      if (\n        r.type.name.startsWith(ResourceTypePrefix.Blob) ||\n        r.type.name.startsWith(ResourceTypePrefix.LS) ||\n        r.type.name.startsWith(ResourceTypePrefix.WorkingDirectory) ||\n        r.type.name.startsWith(ResourceTypePrefix.StorageSpaceAllocation)\n      ) {\n        return true;\n      } else if (\n        r.type.name.startsWith(ResourceTypePrefix.BlobUpload) ||\n        r.type.name.startsWith(ResourceTypePrefix.BlobIndex)\n      ) {\n        return readyAndHasAllOutputsFilled(r);\n      } else if (r.type.name.startsWith(ResourceTypePrefix.PColumnData)) {\n        return readyOrDuplicateOrError(r);\n      } else if (r.type.name.startsWith(ResourceTypePrefix.StreamWorkdir)) {\n        return readyOrDuplicateOrError(r);\n      } else {\n        // Unknown resource type detected\n        // Set used to log this message only once\n        if (!unknownResourceTypeNames.has(r.type.name)) {\n          console.log(\"UNKNOWN RESOURCE TYPE: \" + r.type.name);\n          unknownResourceTypeNames.add(r.type.name);\n        }\n      }\n  }\n  return false;\n};\n"],"mappings":"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"}
+{"version":3,"file":"final.cjs","names":["FinalityTable","ResourceTypeName","ResourceTypePrefix","readyOrDuplicateOrError","isNotNullSignedResourceId","isNullSignedResourceId"],"sources":["../../src/core/final.ts"],"sourcesContent":["import { ResourceTypeName, ResourceTypePrefix } from \"@milaboratories/pl-model-common\";\nimport type { FinalityEntry, FinalityStopRule, FinalResourceDataPredicate } from \"./finality\";\nimport { FinalityTable, readyOrDuplicateOrError } from \"./finality\";\nimport { isNotNullSignedResourceId, isNullSignedResourceId } from \"./types\";\nexport { ResourceTypeName, ResourceTypePrefix };\nexport type { FinalResourceDataPredicate } from \"./finality\";\nexport { readyOrDuplicateOrError } from \"./finality\";\n\n// The finality tables, one layer per consumer. Every layer accepts two backend writes after\n// final: a data-loss error cascade, lifting the error of a stored blob found lost or corrupt to\n// the resources built from it, and the first duplicate's `hasOriginalListeners` flag on its\n// original, backend-internal and never on the wire. An entry's `why` names any other write\n// it accepts. A layer adds only the types whose later writes its consumer does not observe.\n\n// Where the backend's filter stops earlier than the predicate. An early stop is safe: the\n// backend sends a body-less stop marker, and the streaming loader fetches every stopped resource\n// it does not hold as final again without stop rules (field filtering and pruning still apply),\n// so the predicate decides on the fetched body.\nconst earlyOnFieldErrors: FinalityStopRule = {\n  approx: \"readyOrDuplicateOrError\",\n  reason:\n    \"HAS_ERRORS is set by an error on any field, the predicate reads the resource error only; \" +\n    \"an early stop is followed up with a plain fetch\",\n};\nconst earlyOnFieldErrorsWithOutputs: FinalityStopRule = {\n  approx: \"readyAndAllOutputsFilled\",\n  reason:\n    \"HAS_ERRORS is set by an error on any field, the predicate reads the resource error only; \" +\n    \"ALL_OUTPUTS_FINAL, like the predicate, checks every retained field; an early stop is \" +\n    \"followed up with a plain fetch\",\n};\n\nconst value = (name: string): FinalityEntry => ({\n  match: { name },\n  rule: \"always\",\n  why: \"a value, written once at creation\",\n});\n\nconst settledAtReady = (name: string, why: string): FinalityEntry => ({\n  match: { name },\n  rule: \"readyOrDuplicateOrError\",\n  why,\n  stopRule: earlyOnFieldErrors,\n});\n\nconst never = (match: FinalityEntry[\"match\"], why: string): FinalityEntry => ({\n  match,\n  rule: \"never\",\n  why,\n});\n\n/** The base layer: nothing observable (state, fields, KV) changes after the rule holds, whatever\n * the consumer prunes. Exceptions: the data-loss error cascade, the `hasOriginalListeners` flag,\n * and the writes its entries name. */\nexport const StrictFinality: FinalityTable = FinalityTable.of(\"strict\", [\n  value(ResourceTypeName.JsonObject),\n  value(ResourceTypeName.JsonGzObject),\n  value(ResourceTypeName.JsonString),\n  value(ResourceTypeName.JsonArray),\n  value(ResourceTypeName.JsonNumber),\n  value(ResourceTypeName.JsonBool),\n  value(ResourceTypeName.JsonNull),\n  {\n    match: { name: ResourceTypeName.JsonErrorTrace },\n    rule: \"always\",\n    why: \"an error-trace snapshot, populated and locked in its creating transaction\",\n  },\n  value(ResourceTypeName.BContextEnd),\n  value(ResourceTypeName.FrontendFromUrl),\n  value(ResourceTypeName.FrontendFromFolder),\n  value(ResourceTypeName.FrontendFromLocalTgz),\n  value(ResourceTypeName.BObjectSpec),\n  value(ResourceTypeName.Null),\n  value(ResourceTypeName.Binary),\n  {\n    match: { name: ResourceTypeName.JsonResourceError },\n    rule: { custom: (r) => r.type.version === \"1\" },\n    why: \"version 1 is a value, written once at creation\",\n    stopRule: { approx: \"always\", reason: \"a stop rule cannot see the type version\" },\n  },\n  { match: { prefix: ResourceTypePrefix.LS }, rule: \"always\", why: \"no write after creation\" },\n  {\n    match: { prefix: ResourceTypePrefix.WorkingDirectory },\n    rule: \"always\",\n    why: \"no write after creation\",\n  },\n  {\n    match: { prefix: ResourceTypePrefix.StorageSpaceAllocation },\n    rule: \"always\",\n    why: \"no write after creation\",\n  },\n  ...[\n    ResourceTypeName.StdMap,\n    ResourceTypeName.StdMapSlash,\n    ResourceTypeName.EphStdMap,\n    ResourceTypeName.PFrame,\n    ResourceTypeName.ParquetChunk,\n    ResourceTypeName.BContext,\n    ResourceTypeName.BinaryMap,\n    ResourceTypeName.BinaryValue,\n    ResourceTypeName.BlobMap,\n    ResourceTypeName.BResolveSingleNoResult,\n    ResourceTypeName.BQueryResult,\n    ResourceTypeName.TengoLib,\n  ].map((name) =>\n    settledAtReady(name, \"its inputs are final at ready, and no controller fills it afterwards\"),\n  ),\n  ...[\n    ResourceTypeName.TengoTemplate,\n    ResourceTypeName.SoftwareInfo,\n    ResourceTypeName.BlockPackCustom,\n  ].map((name) =>\n    settledAtReady(\n      name,\n      \"its only later write is the `hasOriginalListeners` flag its first duplicate sets\",\n    ),\n  ),\n  settledAtReady(\n    ResourceTypeName.Dummy,\n    \"its only later write is a data-loss error from the Blob whose incarnation field holds it\",\n  ),\n  {\n    match: { prefix: ResourceTypePrefix.PColumnData },\n    rule: \"readyOrDuplicateOrError\",\n    why: \"its inputs are final at ready, and no controller fills it afterwards\",\n    stopRule: earlyOnFieldErrors,\n  },\n  {\n    match: { prefix: ResourceTypePrefix.StreamWorkdir },\n    rule: \"readyOrDuplicateOrError\",\n    why: \"no write after ready\",\n    stopRule: {\n      approx: \"readyOrDuplicateOrError\",\n      reason:\n        \"HAS_ERRORS is set by an error on any field; on ResourceTree walks the project field \" +\n        \"filter also removes every field, `resourceError` included, before decoding, so the \" +\n        \"predicate cannot see an error the filter stops on; an early stop is followed up with \" +\n        \"a plain fetch\",\n    },\n  },\n  {\n    match: { name: ResourceTypeName.BResolveSingle },\n    rule: \"readyAndAllOutputsFilled\",\n    why:\n      \"outputs are locked at creation and assigned after ready, never overwritten; one \" +\n      \"exception: a later context with more than one match sets an error on a resolver that \" +\n      \"already succeeded, and a reader holding it final misses that error\",\n    stopRule: earlyOnFieldErrorsWithOutputs,\n  },\n  {\n    match: { name: ResourceTypeName.BResolveChoice },\n    rule: \"readyAndAllOutputsFilled\",\n    why:\n      \"outputs are locked at creation and point at result maps that are completed and locked \" +\n      \"as resolution finishes\",\n    stopRule: earlyOnFieldErrorsWithOutputs,\n  },\n  never({ name: ResourceTypeName.UserProject }, \"blocks and fields come and go over its life\"),\n  never({ name: ResourceTypeName.Projects }, \"projects are added and removed\"),\n  never({ name: ResourceTypeName.ClientRoot }, \"its fields are added and removed\"),\n  ...[\n    ResourceTypeName.SharingOutbox,\n    ResourceTypeName.SharingState,\n    ResourceTypeName.SharedEnvelope,\n  ].map((name) => never({ name }, \"gains and loses dynamic child fields over its life\")),\n  never(\n    { name: ResourceTypeName.LSProvider },\n    \"its storage fields are rewritten on a controller restart with a changed storage config\",\n  ),\n  never({ name: ResourceTypeName.Blob }, \"its incarnation field is attached or replaced later\"),\n  never({ name: ResourceTypeName.StreamManager }, \"`stream` is reset after an error\"),\n  never({ prefix: ResourceTypePrefix.Blob }, \"its `ctl/file/blobInfo` KV is re-pointed later\"),\n  never(\n    { prefix: ResourceTypePrefix.BlobIndex },\n    \"a controller restart writes its `ctl/ctlsdk/bootstrapDone` KV\",\n  ),\n  never(\n    { prefix: ResourceTypePrefix.BlobUpload },\n    \"the Reset RPC deletes its `ctl/file/storage/uploadState` KV\",\n  ),\n  never(\n    { prefix: ResourceTypePrefix.BlobCopy },\n    \"a controller bootstrap records its `ctl/ctlsdk/bootstrapDone` KV in a separate transaction, which may run after the copy settled\",\n  ),\n  never(\n    { name: ResourceTypeName.WorkingDirectory },\n    \"lock acquisition can write its `internal/locks/lockedBy` KV after creation\",\n  ),\n]);\n\n/** What the transaction resource cache may keep while an entry stays in its LRU. The cache holds\n * state and fields, never KV, so it adds the types whose only later writes are KV. */\nexport const CacheFinality: FinalityTable = StrictFinality.extend(\"cache\", [\n  {\n    match: { prefix: ResourceTypePrefix.Blob },\n    rule: \"always\",\n    why:\n      \"`ctl/file/blobInfo` is re-pointed for the same content: the cache holds no KV, and a \" +\n      \"tree reads only its `sizeBytes`, invariant for the same content\",\n  },\n  {\n    match: { prefix: ResourceTypePrefix.BlobIndex },\n    rule: \"readyAndAllOutputsFilled\",\n    why: \"`ctl/ctlsdk/bootstrapDone` is backend bookkeeping KV; no client reads it\",\n    stopRule: earlyOnFieldErrorsWithOutputs,\n  },\n  {\n    match: { prefix: ResourceTypePrefix.BlobUpload },\n    rule: \"readyAndAllOutputsFilled\",\n    why: \"`ctl/file/storage/uploadState` is backend bookkeeping KV; no client reads it\",\n    stopRule: earlyOnFieldErrorsWithOutputs,\n  },\n  {\n    match: { prefix: ResourceTypePrefix.BlobCopy },\n    rule: \"readyAndAllOutputsFilled\",\n    why:\n      \"outputs are locked at creation; the only later write, the bootstrap's \" +\n      \"`ctl/ctlsdk/bootstrapDone`, is backend bookkeeping KV; no client reads it\",\n    stopRule: earlyOnFieldErrorsWithOutputs,\n  },\n  {\n    match: { name: ResourceTypeName.WorkingDirectory },\n    rule: \"always\",\n    why: \"the lock KV is backend bookkeeping; no client reads it\",\n  },\n]);\n\nfunction streamSwitchedOrErrored(r: Parameters<FinalResourceDataPredicate>[0]): boolean {\n  if (!readyOrDuplicateOrError(r)) return false;\n  if (r.fields === undefined) return true;\n  if (isNotNullSignedResourceId(r.error)) return true;\n  // Fields can be pruned away by the reader: without them nothing proves the switch. The\n  // predicate must not throw, since a throw inside a tree update rebuilds the whole tree.\n  const downloadable = r.fields.find((f) => f.name === \"downloadable\");\n  const stream = r.fields.find((f) => f.name === \"stream\");\n  if (downloadable === undefined || stream === undefined || isNullSignedResourceId(stream.value))\n    return false;\n  // No backend flag marks the switch: equal non-null fields mean the controller's success branch\n  // has switched `stream` to the downloadable blob.\n  return stream.value === downloadable.value;\n}\n\n/**\n * The finality of trees, and the default of `PlClient.finalPredicate`: a resource it calls final\n * leaves the refresh seeds, later bodies for it are ignored, and its mutable-state change sources\n * are retired. It adds Blob and StreamManager under reader assumptions stated at each entry; a\n * consumer that reads what they exclude passes its own predicate.\n */\nexport const TreeFinality: FinalityTable = CacheFinality.extend(\"tree\", [\n  {\n    match: { name: ResourceTypeName.Blob },\n    rule: \"always\",\n    why:\n      \"the incarnation field is replaced later; the project tree prunes Blob's fields, and the \" +\n      \"drivers read a blob by id, never through its fields\",\n    requiresPruning: { type: ResourceTypeName.Blob, fields: \"all\" },\n  },\n  {\n    match: { name: ResourceTypeName.StreamManager },\n    rule: { custom: streamSwitchedOrErrored },\n    why:\n      \"after an error `stream` is reset in a later transaction; default traversal raises the \" +\n      \"error before exposing the fields, so only an `ignoreError` read sees `stream`\",\n    stopRule: {\n      approx: \"readyOrDuplicateOrError\",\n      reason: \"a stop rule cannot compare two fields, so it stops before `stream` switches\",\n    },\n  },\n]);\n\n/** @deprecated use {@link TreeFinality} */\nexport const DefaultFinalResourceDataPredicate: FinalResourceDataPredicate =\n  TreeFinality.predicate();\n"],"mappings":"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"}

package/dist/core/final.d.ts

@@ -1,20 +1,22 @@
-import { BasicResourceData, ResourceData } from "./types.js";
+import { FinalResourceDataPredicate, FinalityTable, readyOrDuplicateOrError } from "./finality.js";
 import { ResourceTypeName, ResourceTypePrefix } from "@milaboratories/pl-model-common";
-import { Optional } from "utility-types";
 //#region src/core/final.d.ts
+/** The base layer: nothing observable (state, fields, KV) changes after the rule holds, whatever
+ * the consumer prunes. Exceptions: the data-loss error cascade, the `hasOriginalListeners` flag,
+ * and the writes its entries name. */
+export declare const StrictFinality: FinalityTable;
+/** What the transaction resource cache may keep while an entry stays in its LRU. The cache holds
+ * state and fields, never KV, so it adds the types whose only later writes are KV. */
+export declare const CacheFinality: FinalityTable;
 /**
- * Function is used to guide multiple layers of caching in pl-client and derived pl-tree.
- *
- * This function defines expected resource-specific state mutation behaviour,
- * if it returns true, system will expect that this data will never change as long as resource exist.
- *
- * If resource data contain information about fields, if should be taken into account, fields are undefined,
- * "final" state should be calculated for "basic" part of resource data only.
+ * The finality of trees, and the default of `PlClient.finalPredicate`: a resource it calls final
+ * leaves the refresh seeds, later bodies for it are ignored, and its mutable-state change sources
+ * are retired. It adds Blob and StreamManager under reader assumptions stated at each entry; a
+ * consumer that reads what they exclude passes its own predicate.
  */
-export type FinalResourceDataPredicate = (resourceData: Optional<ResourceData, "fields">) => boolean;
-export declare function readyOrDuplicateOrError(r: ResourceData | BasicResourceData): boolean;
-/** Default implementation, defining behaviour for built-in resource types. */
+export declare const TreeFinality: FinalityTable;
+/** @deprecated use {@link TreeFinality} */
 export declare const DefaultFinalResourceDataPredicate: FinalResourceDataPredicate;
 //#endregion
-export { ResourceTypeName, ResourceTypePrefix };
+export { type FinalResourceDataPredicate, ResourceTypeName, ResourceTypePrefix, readyOrDuplicateOrError };
 //# sourceMappingURL=final.d.ts.map

package/dist/core/final.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"final.d.ts","names":[],"sources":["../../src/core/final.ts"],"mappings":";;;;;;;;;;;;;YAeY,8BACV,cAAc,SAAS;wBAGT,wBAAwB,GAAG,eAAe;;qBAsB7C,mCAAmC"}
+{"version":3,"file":"final.d.ts","names":[],"sources":["../../src/core/final.ts"],"mappings":";;;;;;qBAsDa,gBAAgB;;;qBA0IhB,eAAe;;;;;;;qBAwDf,cAAc;;qBAuBd,mCAAmC"}