dsh-skill-pool 0.3.7 → 0.4.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/src/store.js CHANGED
@@ -31,14 +31,33 @@
31
31
  * @module dsh-skill-pool/store
32
32
  */
33
33
 
34
+ import { AsyncLocalStorage } from 'node:async_hooks'
34
35
  import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
35
- import { dirname, join } from 'node:path'
36
+ import { dirname, join, resolve as resolvePath } from 'node:path'
36
37
  import { homedir } from 'node:os'
37
38
  import { groupKeyOfSource } from './rules.js'
38
39
 
39
40
  /** Current document version. */
40
41
  export const STATE_VERSION = 4
41
42
 
43
+ /**
44
+ * Absolute state-file paths this Node process has observed.
45
+ *
46
+ * A new `StateStore` (for example after an in-process plugin reload) must not
47
+ * forget that a file existed and mistake its disappearance for a first run.
48
+ * This is an in-memory set: it creates no file, survives module reloads in the
49
+ * same process through `globalThis`, and intentionally cannot survive a Host
50
+ * restart (a deleted file and a genuine first run are then indistinguishable).
51
+ */
52
+ const OBSERVED_STATE_FILES_KEY = Symbol.for('dsh-skill-pool.observed-state-files')
53
+ const observedStateFiles =
54
+ globalThis[OBSERVED_STATE_FILES_KEY] instanceof Set
55
+ ? globalThis[OBSERVED_STATE_FILES_KEY]
56
+ : (globalThis[OBSERVED_STATE_FILES_KEY] = new Set())
57
+
58
+ /** Group keys that would mutate the normalized map's prototype. */
59
+ const FORBIDDEN_GROUP_KEYS = new Set(['__proto__', 'prototype', 'constructor'])
60
+
42
61
  /** The one older version this module upgrades instead of discarding. */
43
62
  export const LEGACY_VERSION = 3
44
63
 
@@ -61,7 +80,7 @@ export const GIT_PROVIDERS = ['github', 'gitlab']
61
80
  export const CHECK_STATUSES = ['up-to-date', 'update-available', 'error']
62
81
 
63
82
  /** Switches the panel may patch. */
64
- export const SETTING_KEYS = ['enabled', 'mcpGate', 'injectSummary', 'gateDefaultSkills']
83
+ export const SETTING_KEYS = ['enabled', 'mcpGate', 'gateDefaultSkills']
65
84
 
66
85
  /** Conservative identifier grammar for resource names and mode ids. */
67
86
  const NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,159}$/
@@ -174,7 +193,7 @@ function cleanSubdir(value) {
174
193
 
175
194
  /** Default settings of a fresh document (§2.1). */
176
195
  export function defaultSettings() {
177
- return { enabled: true, mcpGate: true, injectSummary: true, gateDefaultSkills: false }
196
+ return { enabled: true, mcpGate: true, gateDefaultSkills: false }
178
197
  }
179
198
 
180
199
  /** A fresh, empty document. */
@@ -498,7 +517,6 @@ function migrateV3(source) {
498
517
  const settings = {
499
518
  enabled: rawSettings.enabled !== false,
500
519
  mcpGate: rawSettings.mcpGate !== false,
501
- injectSummary: rawSettings.injectSummary !== false,
502
520
  gateDefaultSkills: rawSettings.gateDefaultSkills === true,
503
521
  }
504
522
  const sources = {}
@@ -563,7 +581,6 @@ export function normalizeState(raw) {
563
581
  const settings = {
564
582
  enabled: rawSettings.enabled !== false,
565
583
  mcpGate: rawSettings.mcpGate !== false,
566
- injectSummary: rawSettings.injectSummary !== false,
567
584
  gateDefaultSkills: rawSettings.gateDefaultSkills === true,
568
585
  }
569
586
 
@@ -586,6 +603,297 @@ export function normalizeState(raw) {
586
603
  }
587
604
  }
588
605
 
606
+ /** Top-level sections every complete v4 document must carry as plain objects. */
607
+ const STATE_SECTIONS = ['settings', 'skills', 'mcp', 'sources', 'groups']
608
+
609
+ /**
610
+ * A state document that cannot be used safely.
611
+ *
612
+ * The code is intentionally stable for the HTTP/status surfaces; the message is
613
+ * a fixed explanation and never contains file bytes, member definitions or
614
+ * credentials. Callers either keep their previous gate (an already-live Agent)
615
+ * or fail closed (a new Agent).
616
+ */
617
+ export class StateReadError extends Error {
618
+ /**
619
+ * @param {string} code - stable error code such as `resource-pool/state-invalid-json`.
620
+ * @param {string} message - safe explanation, never document content.
621
+ */
622
+ constructor(code, message) {
623
+ // Keep diagnostics fixed, single-line and bounded: map keys and version
624
+ // values come from the file and may contain secrets or newlines.
625
+ super(String(message).replace(/[\r\n]+/g, ' ').slice(0, 240))
626
+ this.name = 'StateReadError'
627
+ this.code = code
628
+ this.status = 500
629
+ }
630
+ }
631
+
632
+ /** Throw the one "this document cannot be trusted" error. */
633
+ function invalidDocument(detail) {
634
+ throw new StateReadError(
635
+ 'resource-pool/state-invalid-document',
636
+ `state file is not a valid resource-pool document (${detail}); refusing to overwrite or use it`,
637
+ )
638
+ }
639
+
640
+ /** Require a plain object. */
641
+ function requireObject(value, what) {
642
+ if (!isObject(value)) invalidDocument(`${what} must be an object`)
643
+ }
644
+
645
+ /** Require a boolean when the property is present. */
646
+ function optionalBoolean(value, what) {
647
+ if (value !== undefined && typeof value !== 'boolean') invalidDocument(`${what} must be a boolean`)
648
+ }
649
+
650
+ /** Require a string when the property is present. */
651
+ function optionalStringField(value, what, limit = 4096) {
652
+ if (value === undefined) return
653
+ if (typeof value !== 'string' || value.length > limit) invalidDocument(`${what} must be a string of at most ${limit} characters`)
654
+ }
655
+
656
+ /** Require an array of conservative names. */
657
+ function requireNameList(value, what) {
658
+ if (!Array.isArray(value)) invalidDocument(`${what} must be an array of names`)
659
+ for (const item of value) {
660
+ if (typeof item !== 'string' || cleanName(item) !== item) invalidDocument(`${what} contains an invalid name`)
661
+ }
662
+ }
663
+
664
+ /** Require an array of absolute workspace paths. */
665
+ function requirePathList(value, what) {
666
+ if (!Array.isArray(value)) invalidDocument(`${what} must be an array of workspace paths`)
667
+ for (const item of value) {
668
+ if (typeof item !== 'string' || normalizePath(item).length === 0) invalidDocument(`${what} contains an invalid workspace path`)
669
+ }
670
+ }
671
+
672
+ /** Validate the settings switches. v3 allowed some switches to be absent. */
673
+ function validateSettings(raw, { requireAll }) {
674
+ requireObject(raw, 'settings')
675
+ for (const key of SETTING_KEYS) {
676
+ if (requireAll && !Object.hasOwn(raw, key)) invalidDocument(`settings.${key} is missing`)
677
+ optionalBoolean(raw[key], `settings.${key}`)
678
+ }
679
+ if (typeof raw.enabled !== 'boolean') invalidDocument('settings.enabled must be a boolean')
680
+ }
681
+
682
+ /** Validate the optional inheritance markers of a v4 skill member. */
683
+ function validateInheritance(raw, what) {
684
+ for (const key of ['modesFrom', 'workspacesFrom']) {
685
+ if (raw[key] !== undefined && raw[key] !== 'group' && raw[key] !== 'self') {
686
+ invalidDocument(`${what}.${key} must be 'group' or 'self'`)
687
+ }
688
+ }
689
+ }
690
+
691
+ /** Validate one stored MCP connection definition without echoing it. */
692
+ function validateDefinition(raw, what) {
693
+ requireObject(raw, what)
694
+ if (raw.transport !== undefined && !MCP_TRANSPORTS.includes(raw.transport)) invalidDocument(`${what}.transport is unsupported`)
695
+ for (const key of ['serverName', 'url', 'command', 'cwd']) optionalStringField(raw[key], `${what}.${key}`, 4096)
696
+ if (raw.args !== undefined) {
697
+ if (!Array.isArray(raw.args) || raw.args.some((arg) => typeof arg !== 'string')) {
698
+ invalidDocument(`${what}.args must be an array of strings`)
699
+ }
700
+ }
701
+ for (const key of ['headers', 'env']) {
702
+ if (raw[key] === undefined) continue
703
+ requireObject(raw[key], `${what}.${key}`)
704
+ for (const [name, value] of Object.entries(raw[key])) {
705
+ if (typeof name !== 'string' || name.length === 0 || name.length > 256 || typeof value !== 'string') {
706
+ invalidDocument(`${what}.${key} contains an invalid entry`)
707
+ }
708
+ }
709
+ }
710
+ }
711
+
712
+ /** Validate one pool member (`skills` / `mcp`). */
713
+ function validateMember(raw, what, { version, kind, sources }) {
714
+ requireObject(raw, what)
715
+ if (typeof raw.enabled !== 'boolean') invalidDocument(`${what}.enabled must be a boolean`)
716
+ requireNameList(raw.modes, `${what}.modes`)
717
+ requirePathList(raw.workspaces, `${what}.workspaces`)
718
+ optionalStringField(raw.installedAt, `${what}.installedAt`, 64)
719
+ if (version === STATE_VERSION) validateInheritance(raw, what)
720
+ if (kind === 'skill') {
721
+ optionalStringField(raw.sourceId, `${what}.sourceId`, 128)
722
+ optionalStringField(raw.digest, `${what}.digest`, 128)
723
+ if (
724
+ version === STATE_VERSION &&
725
+ typeof raw.sourceId === 'string' &&
726
+ raw.sourceId.length > 0 &&
727
+ isObject(sources) &&
728
+ !Object.hasOwn(sources, raw.sourceId) &&
729
+ (raw.modesFrom !== 'self' || raw.workspacesFrom !== 'self')
730
+ ) {
731
+ invalidDocument(`${what}.sourceId references a missing source while its scope inherits; refusing to resolve the inheritance`)
732
+ }
733
+ }
734
+ if (kind === 'mcp') {
735
+ if (raw.definition !== undefined) validateDefinition(raw.definition, `${what}.definition`)
736
+ }
737
+ }
738
+
739
+ /** Validate one member map. */
740
+ function validateMembers(raw, what, options) {
741
+ requireObject(raw, what)
742
+ for (const [key, value] of Object.entries(raw)) {
743
+ if (cleanName(key) !== key) invalidDocument(`${what} contains an invalid member key`)
744
+ validateMember(value, `${what} member`, options)
745
+ }
746
+ }
747
+
748
+ /** Validate the optional `lastCheck` record of a Git source. */
749
+ function validateLastCheck(raw, what) {
750
+ requireObject(raw, what)
751
+ if (!CHECK_STATUSES.includes(raw.status)) invalidDocument(`${what}.status is unsupported`)
752
+ for (const key of ['at', 'remote', 'error']) optionalStringField(raw[key], `${what}.${key}`, 1024)
753
+ }
754
+
755
+ /** Validate one source record. */
756
+ function validateSource(raw, key, what) {
757
+ requireObject(raw, what)
758
+ if (typeof raw.id !== 'string' || cleanName(raw.id) !== raw.id || raw.id !== key) {
759
+ invalidDocument(`${what}.id must be a valid name matching its map key`)
760
+ }
761
+ if (!SOURCE_KINDS.includes(raw.kind)) invalidDocument(`${what}.kind is unsupported`)
762
+ optionalStringField(raw.label, `${what}.label`, 160)
763
+ if (raw.skills !== undefined) requireNameList(raw.skills, `${what}.skills`)
764
+ if (raw.excluded !== undefined) requireNameList(raw.excluded, `${what}.excluded`)
765
+ optionalStringField(raw.digest, `${what}.digest`, 128)
766
+ optionalStringField(raw.createdAt, `${what}.createdAt`, 64)
767
+ if (raw.kind !== 'git') return
768
+ if (deriveGit(raw) === null) invalidDocument(`${what} does not name a usable Git repository`)
769
+ if (raw.provider !== undefined && !GIT_PROVIDERS.includes(raw.provider)) invalidDocument(`${what}.provider is unsupported`)
770
+ for (const sub of ['url', 'project', 'branch', 'subdir', 'sha', 'tokenCredential']) {
771
+ optionalStringField(raw[sub], `${what}.${sub}`, 2048)
772
+ }
773
+ if (raw.lastCheck !== undefined) validateLastCheck(raw.lastCheck, `${what}.lastCheck`)
774
+ }
775
+
776
+ /** Validate the `sources` map. */
777
+ function validateSources(raw) {
778
+ requireObject(raw, 'sources')
779
+ for (const [key, value] of Object.entries(raw)) validateSource(value, key, 'sources entry')
780
+ }
781
+
782
+ /** Validate one group record (`repo:<project>` / `import:<sourceId>`). */
783
+ function validateGroup(raw, key, what) {
784
+ requireObject(raw, what)
785
+ if (raw.key !== undefined && raw.key !== key) invalidDocument(`${what}.key must match its map key`)
786
+ if (raw.kind !== undefined && !GROUP_KINDS.includes(raw.kind)) invalidDocument(`${what}.kind is unsupported`)
787
+ if (typeof raw.enabled !== 'boolean') invalidDocument(`${what}.enabled must be a boolean`)
788
+ requireNameList(raw.modes, `${what}.modes`)
789
+ requirePathList(raw.workspaces, `${what}.workspaces`)
790
+ if (
791
+ typeof key !== 'string' ||
792
+ key.length === 0 ||
793
+ key.length > 512 ||
794
+ /[\u0000-\u001f\u007f]/.test(key) ||
795
+ FORBIDDEN_GROUP_KEYS.has(key) ||
796
+ key in Object.prototype
797
+ ) {
798
+ invalidDocument(`${what} has an invalid group key`)
799
+ }
800
+ const repoKey = key.startsWith('repo:')
801
+ const importKey = key.startsWith('import:')
802
+ if (repoKey && key.length <= 'repo:'.length) invalidDocument(`${what} has an invalid group key`)
803
+ if (importKey && key.length <= 'import:'.length) invalidDocument(`${what} has an invalid group key`)
804
+ if (raw.kind !== undefined && repoKey && raw.kind !== 'repo') invalidDocument(`${what}.kind does not match its key`)
805
+ if (raw.kind !== undefined && importKey && raw.kind !== 'import') invalidDocument(`${what}.kind does not match its key`)
806
+ }
807
+
808
+ /** Validate the `groups` map. */
809
+ function validateGroups(raw) {
810
+ requireObject(raw, 'groups')
811
+ for (const [key, value] of Object.entries(raw)) validateGroup(value, key, 'groups entry')
812
+ }
813
+
814
+ /**
815
+ * Validate a stored document before it is trusted for gating.
816
+ *
817
+ * `normalizeState` is deliberately lenient for pure migration/write helpers;
818
+ * reading a file is different: silently repairing a damaged document can widen
819
+ * what an Agent may reach. This function accepts exactly the complete v4 shape
820
+ * (and the v3 shape the explicit migration understands) and rejects anything it
821
+ * would otherwise have to invent, drop, or reinterpret.
822
+ *
823
+ * @param {unknown} raw - parsed JSON document.
824
+ * @returns {object} normalized v4 document.
825
+ * @throws {StateReadError} when the document is invalid or unsupported.
826
+ */
827
+ export function normalizeReadableState(raw) {
828
+ if (!isObject(raw)) {
829
+ throw new StateReadError('resource-pool/state-not-object', 'state file is not a JSON object; refusing to overwrite or use it')
830
+ }
831
+ if (raw.version === LEGACY_VERSION) {
832
+ validateSettings(raw.settings, { requireAll: false })
833
+ if (raw.groups !== undefined) {
834
+ if (!isObject(raw.groups)) invalidDocument('v3 document has a non-object "groups" section')
835
+ if (Object.keys(raw.groups).length > 0) {
836
+ invalidDocument('v3 document contains v4-only groups; refusing to migrate away their scope')
837
+ }
838
+ }
839
+ for (const section of ['skills', 'mcp']) {
840
+ if (!isObject(raw[section])) continue
841
+ for (const member of Object.values(raw[section])) {
842
+ if (!isObject(member)) continue
843
+ if (member.modesFrom !== undefined || member.workspacesFrom !== undefined) {
844
+ invalidDocument('v3 document contains v4-only inheritance markers; refusing to reinterpret its scope')
845
+ }
846
+ }
847
+ }
848
+ validateSources(raw.sources)
849
+ validateMembers(raw.skills, 'skills', { version: LEGACY_VERSION, kind: 'skill', sources: raw.sources })
850
+ validateMembers(raw.mcp, 'mcp', { version: LEGACY_VERSION, kind: 'mcp', sources: raw.sources })
851
+ return normalizeState(migrateV3(raw))
852
+ }
853
+ if (raw.version !== STATE_VERSION) {
854
+ throw new StateReadError(
855
+ 'resource-pool/state-unsupported-version',
856
+ 'state file uses an unsupported version; refusing to overwrite or use it',
857
+ )
858
+ }
859
+ for (const section of STATE_SECTIONS) {
860
+ if (!isObject(raw[section])) invalidDocument(`missing or invalid "${section}" section`)
861
+ }
862
+ validateSettings(raw.settings, { requireAll: true })
863
+ validateSources(raw.sources)
864
+ validateGroups(raw.groups)
865
+ validateMembers(raw.skills, 'skills', { version: STATE_VERSION, kind: 'skill', sources: raw.sources })
866
+ validateMembers(raw.mcp, 'mcp', { version: STATE_VERSION, kind: 'mcp', sources: raw.sources })
867
+ return normalizeState(raw)
868
+ }
869
+
870
+ /**
871
+ * Validate the document an update mutator returned.
872
+ *
873
+ * `normalizeState` treats anything that is not a complete v4 document as an
874
+ * empty default, so persisting an accidental `undefined` result (a mutation
875
+ * that forgot to return, or an async mutator that resolved to nothing) — or a
876
+ * fragment such as `{version: 4}` — would silently erase every stored member
877
+ * and credential. Refuse anything incomplete before it can reach the file.
878
+ *
879
+ * @param {unknown} next - mutation result.
880
+ * @returns {object} the same document when it is acceptable.
881
+ * @throws {TypeError} when the result is not a complete v4 document.
882
+ */
883
+ function assertStateDocument(next) {
884
+ if (!isObject(next) || next.version !== STATE_VERSION) {
885
+ throw new TypeError('StateStore.update(mutate) must return a complete v4 state document')
886
+ }
887
+ for (const section of STATE_SECTIONS) {
888
+ if (!isObject(next[section])) {
889
+ throw new TypeError(
890
+ `StateStore.update(mutate) must return a complete v4 state document: "${section}" must be an object`,
891
+ )
892
+ }
893
+ }
894
+ return next
895
+ }
896
+
589
897
  /**
590
898
  * Merge a settings patch over a normalized document.
591
899
  * Unknown keys (including the retired `enforcePool`) are ignored.
@@ -720,46 +1028,204 @@ export function withoutExcluded(names, excluded) {
720
1028
  export class StateStore {
721
1029
  constructor({ file, logger, version = '0.3.0' } = {}) {
722
1030
  this.file = typeof file === 'string' && file.length > 0 ? file : statePath()
1031
+ this.key = resolvePath(this.file)
723
1032
  this.logger = logger
724
1033
  this.version = version
725
1034
  this.cached = undefined
726
1035
  this.writeChain = Promise.resolve()
1036
+ // Marks the async context of a task currently running on `writeChain`, so a
1037
+ // nested write/update can be rejected instead of waiting on itself forever.
1038
+ this.taskContext = new AsyncLocalStorage()
1039
+ // Whether this Store instance has ever successfully read or written the
1040
+ // document. A later ENOENT is then a failure, not a fresh first run. A new
1041
+ // process cannot distinguish a deleted file from a genuine first run; that
1042
+ // boundary is documented in README/CONTRACTS.
1043
+ this.everLoaded = false
1044
+ // Whether the path was ever observed to exist (even if its bytes failed to
1045
+ // parse). Deleting it afterwards is still abnormal.
1046
+ this.everObserved = false
727
1047
  }
728
1048
 
729
- /** Read the document, caching the normalized result. */
1049
+ /**
1050
+ * Decode and validate one state text.
1051
+ *
1052
+ * @param {string} text - raw file contents.
1053
+ * @returns {object} normalized v4 document.
1054
+ * @throws {StateReadError} when the bytes are not a readable state document.
1055
+ */
1056
+ #decode(text) {
1057
+ let raw
1058
+ try {
1059
+ raw = JSON.parse(text)
1060
+ } catch {
1061
+ throw new StateReadError('resource-pool/state-invalid-json', 'state file is not valid JSON; refusing to overwrite or use it')
1062
+ }
1063
+ const state = normalizeReadableState(raw)
1064
+ this.everLoaded = true
1065
+ return state
1066
+ }
1067
+
1068
+ /**
1069
+ * Read the document, caching the normalized result.
1070
+ *
1071
+ * A missing file is a valid first run only until this Store has seen the
1072
+ * document. Every other failure throws a {@link StateReadError}; returning
1073
+ * defaults here would silently widen the pool (an empty pool does not gate).
1074
+ *
1075
+ * @param {{fresh?: boolean}} [options] - force a disk read.
1076
+ * @returns {Promise<object>} normalized v4 document.
1077
+ * @throws {StateReadError} when the file is missing after a successful read,
1078
+ * unreadable, corrupt, unsupported or semantically invalid.
1079
+ */
730
1080
  async read({ fresh = false } = {}) {
731
1081
  if (!fresh && this.cached !== undefined) return this.cached
732
- let raw = null
1082
+ let text
733
1083
  try {
734
- raw = JSON.parse(await readFile(this.file, 'utf8'))
1084
+ text = await readFile(this.file, 'utf8')
735
1085
  } catch (error) {
736
- if (error?.code !== 'ENOENT') this.logger?.warn?.('[skill-pool] state unreadable; starting from defaults')
737
- raw = null
1086
+ if (error?.code !== 'ENOENT') {
1087
+ this.everObserved = true
1088
+ observedStateFiles.add(this.key)
1089
+ throw new StateReadError('resource-pool/state-unreadable', 'state file could not be read; refusing to overwrite or use it')
1090
+ }
1091
+ if (this.everLoaded || this.everObserved || observedStateFiles.has(this.key)) {
1092
+ throw new StateReadError(
1093
+ 'resource-pool/state-missing',
1094
+ 'state file disappeared after it was known to exist; refusing to treat it as a first run',
1095
+ )
1096
+ }
1097
+ this.cached = defaultState()
1098
+ return this.cached
738
1099
  }
739
- this.cached = normalizeState(raw)
1100
+ this.everObserved = true
1101
+ observedStateFiles.add(this.key)
1102
+ this.cached = this.#decode(text)
740
1103
  return this.cached
741
1104
  }
742
1105
 
743
- /** Persist a normalized document and update the cache. */
744
- async write(state) {
745
- const normalized = normalizeState(state)
746
- const run = this.writeChain.then(async () => {
747
- await mkdir(dirname(this.file), { recursive: true })
748
- const temporary = `${this.file}.${process.pid}.${Date.now()}.tmp`
749
- // 0600: an MCP member may carry an `Authorization` header, so the pool
750
- // document holds the same secrets a profile patch would.
751
- await writeFile(temporary, `${JSON.stringify(normalized, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 })
752
- await rename(temporary, this.file)
753
- this.cached = normalized
754
- return normalized
755
- })
756
- this.writeChain = run.then(() => undefined, () => undefined)
1106
+ /**
1107
+ * Queue one operation behind every write/update already scheduled.
1108
+ *
1109
+ * A rejection settles only the operation's own promise: the queue itself is
1110
+ * reset to a fulfilled promise, so one failed save never wedges later ones.
1111
+ *
1112
+ * A call made from inside a queued task's async context (typically `await
1113
+ * store.write(...)` inside an `update` mutator) is rejected immediately: it
1114
+ * would queue behind the very task awaiting it and deadlock the store.
1115
+ * AsyncLocalStorage distinguishes those descendants from independent callers
1116
+ * that merely arrive while the queue is busy — a process-wide "busy" flag
1117
+ * would wrongly reject those external calls too.
1118
+ *
1119
+ * @param {() => Promise<object>} task - operation to run once its turn comes.
1120
+ * @returns {Promise<object>} the operation's result.
1121
+ */
1122
+ #enqueue(task) {
1123
+ if (this.taskContext.getStore() === true) {
1124
+ return Promise.reject(
1125
+ new Error(
1126
+ 'StateStore.write/update cannot be called from inside an update mutator: it would wait on the same queue',
1127
+ ),
1128
+ )
1129
+ }
1130
+ const run = this.writeChain.then(() => this.taskContext.run(true, task))
1131
+ this.writeChain = run.then(
1132
+ () => undefined,
1133
+ () => undefined,
1134
+ )
757
1135
  return run
758
1136
  }
759
1137
 
760
- /** Apply one mutation to a fresh read and persist the result. */
1138
+ /**
1139
+ * Read the document for a queued read-modify-write, failing instead of
1140
+ * guessing.
1141
+ *
1142
+ * An update is about to overwrite the file, so it uses the same fail-closed
1143
+ * validation as `read()`: a JSON parse error, unsupported version, semantic
1144
+ * invalidity or I/O error must abort the save instead of replacing
1145
+ * credential-bearing state with defaults. Only a missing file (ENOENT)
1146
+ * legitimately starts from defaults, and only before this store has observed
1147
+ * the document.
1148
+ *
1149
+ * @returns {Promise<object>} normalized on-disk document.
1150
+ */
1151
+ async #readStrict() {
1152
+ let text
1153
+ try {
1154
+ text = await readFile(this.file, 'utf8')
1155
+ } catch (error) {
1156
+ if (error?.code === 'ENOENT') {
1157
+ if (this.everLoaded || this.everObserved || observedStateFiles.has(this.key)) {
1158
+ throw new StateReadError(
1159
+ 'resource-pool/state-missing',
1160
+ 'state file disappeared after it was known to exist; refusing to overwrite it',
1161
+ )
1162
+ }
1163
+ this.cached = defaultState()
1164
+ return this.cached
1165
+ }
1166
+ this.everObserved = true
1167
+ observedStateFiles.add(this.key)
1168
+ throw new StateReadError('resource-pool/state-unreadable', 'state file could not be read; refusing to overwrite it')
1169
+ }
1170
+ this.everObserved = true
1171
+ observedStateFiles.add(this.key)
1172
+ this.cached = this.#decode(text)
1173
+ return this.cached
1174
+ }
1175
+
1176
+ /**
1177
+ * Persist one normalized document atomically, then update the cache.
1178
+ *
1179
+ * Only the queue may call this: `write`/`update` enqueue, so calling them from
1180
+ * inside a queued task would wait on itself and deadlock.
1181
+ *
1182
+ * @param {object} normalized - normalized document.
1183
+ * @returns {Promise<object>} the persisted document.
1184
+ */
1185
+ async #persist(normalized) {
1186
+ await mkdir(dirname(this.file), { recursive: true })
1187
+ const temporary = `${this.file}.${process.pid}.${Date.now()}.tmp`
1188
+ // 0600: an MCP member may carry an `Authorization` header, so the pool
1189
+ // document holds the same secrets a profile patch would.
1190
+ await writeFile(temporary, `${JSON.stringify(normalized, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 })
1191
+ await rename(temporary, this.file)
1192
+ this.cached = normalized
1193
+ this.everLoaded = true
1194
+ this.everObserved = true
1195
+ observedStateFiles.add(this.key)
1196
+ return normalized
1197
+ }
1198
+
1199
+ /** Persist a complete, readable document, queued behind earlier writes/updates. */
1200
+ async write(state) {
1201
+ // Validate before queueing: a direct write must not be able to replace a
1202
+ // credential-bearing document with a fragment or a semantically broken one.
1203
+ const normalized = normalizeReadableState(state)
1204
+ return this.#enqueue(() => this.#persist(normalized))
1205
+ }
1206
+
1207
+ /**
1208
+ * Apply one mutation to a fresh read and persist the result as one queued
1209
+ * read-modify-write.
1210
+ *
1211
+ * The strict fresh read happens inside the queue, after every earlier
1212
+ * write/update has settled. Two concurrent updates therefore see each other's
1213
+ * result instead of overwriting it, and direct `write` calls keep their call
1214
+ * order. `mutate` may be async, but must resolve to a complete v4 document;
1215
+ * an invalid result is rejected before anything is written. A nested
1216
+ * `store.write`/`store.update` inside `mutate` is rejected instead of
1217
+ * enqueueing behind itself, which would deadlock the queue.
1218
+ *
1219
+ * @param {(state: object) => object|Promise<object>} mutate - pure mutation.
1220
+ * @returns {Promise<object>} the persisted document.
1221
+ */
761
1222
  async update(mutate) {
762
- const current = await this.read({ fresh: true })
763
- return this.write(mutate(current))
1223
+ return this.#enqueue(async () => {
1224
+ const current = await this.#readStrict()
1225
+ const next = assertStateDocument(await mutate(current))
1226
+ // Validate the mutation's result with the same fail-closed rules as a
1227
+ // disk read: never persist a document we would refuse to read back.
1228
+ return this.#persist(normalizeReadableState(next))
1229
+ })
764
1230
  }
765
1231
  }