dsh-ptc-plus 0.3.2 → 0.4.2

package/internal/stateful-root-runtime.js

@@ -0,0 +1,340 @@
+/** Session logical identities, independent of the native cell's lexical frame. */
+import { createDynamicEnvironmentRuntime } from './dynamic-environment-runtime.js'
+import { captureCompilerIntrinsics, moduleRuntimeIntrinsics as internal } from './compiler-intrinsics.js'
+
+const { Map, Set, Object, Proxy, mapGet, mapSet, mapHas, mapClear, mapForEach,
+  setHas, setAdd, includes, appendArray, stringify } = internal
+
+export function createStatefulRootRuntime({ readAmbient, typeofAmbient, writeAmbient, deleteAmbient,
+  canWriteAmbient = () => true,
+  errors,
+  dynamicIntrinsics, importModule = (source, options) => import(source, options),
+  hasOverlay = () => false, hasAmbient, publish = () => {}, changed = () => {}, refresh = () => {} }) {
+  const entries = new Map()
+  const intrinsics = captureCompilerIntrinsics(dynamicIntrinsics?.realmFunction)
+  errors ??= intrinsics
+  const dynamicRuntime = createDynamicEnvironmentRuntime({ ...dynamicIntrinsics, importModule })
+  const moduleRuntime = dynamicIntrinsics === undefined ? undefined : createDynamicEnvironmentRuntime()
+  let commit
+  const read = name => {
+    refresh(name)
+    const entry = mapGet(entries, name)
+    return hasOverlay(name) || entry === undefined || entry.object === true || entry.deleted === true
+      ? readAmbient(name) : entry.read === undefined ? entry.value : entry.read()
+  }
+  const storeValue = (name, value, { source = 'local', readOnly = false, declaration = false,
+    strict = false, target, nativeKind } = {}) => {
+    refresh(name)
+    const previous = mapGet(entries, name)
+    if (hasOverlay(name)) {
+      // A hard request overlay is not shadowable, so this store cannot publish a session identity.
+      // A declaration is the overlay's own pre-emption and stays absorbed; an actual write that the
+      // ambient property cannot accept must fail observably instead of being discarded.
+      if (!declaration && !canWriteAmbient(name)) {
+        throw new errors.TypeError(`${name} cannot be overwritten because reserved program bindings are not shadowable`)
+      }
+      writeAmbient(name, value, strict)
+      return undefined
+    }
+    if (!declaration && (previous === undefined || previous.object === true || previous.deleted === true) && writeAmbient !== undefined) {
+      writeAmbient(name, value, strict)
+      mapSet(entries, name, { source, object: true, ...(previous?.legacyWritable === true ? { legacyWritable: true } : {}) })
+    } else if (previous?.legacyWritable === true && writeAmbient !== undefined
+      && (previous.object !== true || canWriteAmbient(name))) {
+      writeAmbient(name, value)
+      mapSet(entries, name, { ...previous, source, readOnly })
+    } else mapSet(entries, name, { value, source, readOnly, ...(previous?.nativeKind === undefined ? {} : { nativeKind: previous.nativeKind }) })
+    const writeTarget = target ?? (declaration ? undefined : previous?.writeTarget)
+    const entry = mapGet(entries, name)
+    delete entry.writeTarget
+    if (writeTarget !== undefined) entry.writeTarget = writeTarget
+    if (nativeKind !== undefined) entry.nativeKind = nativeKind
+    return entry
+  }
+  const write = (name, value, options) => {
+    const entry = storeValue(name, value, options)
+    if (entry === undefined) return value
+    if (entry.object !== true) publish(name, () => read(name), value => write(name, value))
+    changed(name, entry.source)
+    return value
+  }
+  const begin = ({ declared = [], known = [], readOnly = [], legacyImports = [], legacyWritable = [], legacyLexicals = [], legacyObjects = [],
+    declarationKinds = [], declaredKinds = [], callableSources = [], languageSemantics = 'stateful-v1', committed }) => {
+    dynamicRuntime.registerSources(callableSources)
+    commit = committed
+    const kinds = new Map()
+    for (let index = 0; index < declarationKinds.length; index++) mapSet(kinds, declarationKinds[index][0], declarationKinds[index][1])
+    for (let index = 0; index < legacyImports.length; index++) {
+      const name = legacyImports[index][0], binding = legacyImports[index][1]
+      if (!mapHas(entries, name)) mapSet(entries, name, { source: 'import', read: () => {
+        const namespace = readAmbient(binding.namespace)
+        return binding.imported === undefined ? namespace : namespace[binding.imported]
+      } })
+    }
+    for (let index = 0; index < legacyWritable.length; index++) {
+      const name = legacyWritable[index]
+      if (!mapHas(entries, name)) mapSet(entries, name, { source: 'local', legacyWritable: true,
+        ...(includes(legacyObjects, name) ? { object: true } : {}), read: () => readAmbient(name) })
+    }
+    for (let index = 0; index < legacyLexicals.length; index++) {
+      const name = legacyLexicals[index]
+      if (!mapHas(entries, name)) mapSet(entries, name, { source: 'local', readOnly: true, read: () => readAmbient(name) })
+    }
+    const protectedNames = new Set()
+    if (languageSemantics === 'protected-v1') {
+      for (let index = 0; index < readOnly.length; index++) setAdd(protectedNames, readOnly[index])
+      mapForEach(entries, (entry, name) => { if (entry.readOnly) setAdd(protectedNames, name) })
+    }
+    const fresh = new Set()
+    for (let index = 0; index < declared.length; index++) {
+      const name = declared[index]
+      if (!mapHas(entries, name) && !includes(known, name)) setAdd(fresh, name)
+    }
+    const checkInitialized = name => {
+      if (!hasOverlay(name) && setHas(fresh, name) && !mapHas(entries, name)) throw new errors.ReferenceError(`Cannot access '${name}' before initialization`)
+    }
+    const get = name => {
+      checkInitialized(name)
+      return read(name)
+    }
+    const checkWritable = name => {
+      if (languageSemantics === 'protected-v1') checkInitialized(name)
+      if (languageSemantics === 'protected-v1' && (setHas(protectedNames, name) || mapGet(entries, name)?.readOnly === true)) {
+        throw new errors.TypeError('Assignment to constant variable.')
+      }
+    }
+    const needsDeclaration = name => {
+      const entry = mapGet(entries, name)
+      return entry === undefined && (setHas(fresh, name) || hasAmbient !== undefined && !hasAmbient(name))
+        || (entry?.object === true || entry?.deleted === true) && !hasAmbient(name)
+    }
+    const remove = name => {
+      const entry = mapGet(entries, name)
+      if (hasOverlay(name) || entry?.object || entry?.deleted || entry === undefined && !setHas(fresh, name)) return deleteAmbient(name)
+      if (entry?.nativeKind !== 'eval-var') return false
+      mapSet(entries, name, { ...entry, deleted: true })
+      return true
+    }
+    const values = new Proxy(Object.create(null), {
+      get: (_, name) => get(name),
+      set: (_, name, value) => {
+        checkWritable(name)
+        write(name, value)
+        return true
+      },
+      deleteProperty: (_, name) => remove(name),
+    })
+    const result = {
+      values,
+      intrinsics,
+      importModule,
+      dynamic({ realm = false } = {}) {
+        const pendingKinds = new Map()
+        for (let index = 0; index < declaredKinds.length; index++) mapSet(pendingKinds, declaredKinds[index][0], declaredKinds[index][1])
+        const kindFor = name => {
+          const entry = mapGet(entries, name)
+          if (hasOverlay(name) || entry?.deleted) return undefined
+          if (entry?.object || entry === undefined && realm && !setHas(fresh, name)) return realm && hasAmbient(name) ? 'var' : undefined
+          return entry === undefined ? setHas(fresh, name) ? mapGet(pendingKinds, name) ?? 'let' : undefined : entry.nativeKind ?? 'let'
+        }
+        const variableKind = kind => includes(['var', 'eval-var', 'hoisted'], kind)
+        const descriptor = (name, kind) => ({
+          kind,
+          get: () => get(name),
+          set(value, strict, origin, writeTarget) {
+            result.reference(name, strict, writeTarget ?? (origin === undefined ? undefined : `${origin}:${stringify(name)}`)).value = value
+          },
+          delete() {
+            const entry = mapGet(entries, name)
+            if (realm && (entry === undefined || entry.object)) return delete values[name]
+            return remove(name)
+          },
+        })
+        const lexicalFrame = { has: name => kindFor(name) !== undefined && !variableKind(kindFor(name)),
+          get: name => lexicalFrame.has(name) ? descriptor(name, kindFor(name)) : undefined }
+        const varFrame = { has: name => variableKind(kindFor(name)), get: name => varFrame.has(name) ? descriptor(name, 'var') : undefined,
+          set() {} }
+        return dynamicRuntime.environment({
+          varFrame, frames: [{ kind: 'lexical', bindings: lexicalFrame }],
+          declareVars: realm ? (names, functionNames) => {
+            const globals = []
+            for (let index = 0; index < names.length; index++) {
+              const name = names[index], entry = mapGet(entries, name)
+              if (hasOverlay(name) || entry === undefined || entry.object === true || entry.deleted === true) appendArray(globals, name)
+            }
+            dynamicRuntime.declareGlobals(globals, functionNames)
+          } : undefined,
+          ambient(name, strict, origin, writeTarget) {
+            return dynamicRuntime.reference(name, {
+              get: () => get(name),
+              set: value => { result.reference(name, strict, writeTarget ?? (origin === undefined ? undefined : `${origin}:${stringify(name)}`)).value = value },
+              typeof: () => result.typeof(name),
+              delete: () => delete values[name],
+            }, undefined, strict)
+          },
+          createVar(name, origin) {
+            if (!mapHas(entries, name) || mapGet(entries, name).object || mapGet(entries, name).deleted) {
+              // A hard overlay pre-empts a realm-level var declaration, so that declaration is
+          // absorbed instead of being written through to a property the ambient cannot accept.
+          write(name, undefined, { declaration: !realm || hasOverlay(name), nativeKind: 'eval-var',
+                target: origin === undefined ? undefined : `${origin}:${stringify(name)}` })
+            }
+            return descriptor(name, 'var')
+          },
+        })
+      },
+      typeof(name) {
+        // Native typeof distinguishes an unresolvable reference from any error
+        // thrown by resolving a getter, including errors from another realm.
+        if (hasOverlay(name) || !mapHas(entries, name) && !setHas(fresh, name)
+          || mapGet(entries, name)?.object === true || mapGet(entries, name)?.deleted === true) return typeofAmbient(name)
+        return typeof get(name)
+      },
+      declare(name, target) {
+        if (needsDeclaration(name)) {
+          write(name, undefined, { readOnly: setHas(protectedNames, name), declaration: true,
+            nativeKind: mapGet(kinds, target) ?? 'var' })
+          commit(target)
+        }
+      },
+      assign(name, value, target) {
+        write(name, value, { readOnly: setHas(protectedNames, name), declaration: true,
+          nativeKind: mapGet(kinds, target) ?? 'let' })
+        commit(target)
+        return value
+      },
+      reference(name, strict, target) {
+        return new Proxy(Object.create(null), {
+          get: () => get(name),
+          set: (_, key, value) => {
+            checkWritable(name)
+            write(name, value, { strict, target })
+            return true
+          },
+        })
+      },
+      import(name, namespace, imported, target) {
+        mapSet(entries, name, { source: 'import', nativeKind: 'const', readOnly: setHas(protectedNames, name), read: () => imported === null ? namespace : namespace[imported] })
+        publish(name, () => read(name), value => write(name, value))
+        changed(name, 'import')
+        commit(target)
+      },
+      link(name, linked, target) {
+        if (name !== linked) {
+          mapSet(entries, name, { source: 'local', read: () => read(linked) })
+          publish(name, () => read(name), value => write(name, value))
+          changed(name, 'local')
+        }
+        commit(target)
+      },
+      candidate(names) {
+        const pending = new Map()
+        let published = false
+        // Pattern targets initialize values; source references enforce writes.
+        const values = new Proxy(Object.create(null), {
+          deleteProperty: (_, name) => published ? remove(name) : false,
+          get: (_, name) => {
+            if (published) return read(name)
+            return mapHas(pending, name) ? mapGet(pending, name) : get(name)
+          },
+          set: (_, name, value) => {
+            if (published) {
+              checkWritable(name)
+              write(name, value)
+            }
+            else mapSet(pending, name, value)
+            return true
+          },
+        })
+        return {
+          values,
+          reference(name, strict = false, target) {
+            return dynamicRuntime.reference(name, {
+              get: () => values[name],
+              set(value) {
+                if (!published && mapHas(pending, name)) {
+                  if (setHas(protectedNames, name)) throw new errors.TypeError('Assignment to constant variable.')
+                } else checkWritable(name)
+                if (published) write(name, value, { strict, target })
+                else mapSet(pending, name, value)
+              },
+              delete: () => published ? remove(name) : false,
+            }, undefined, strict)
+          },
+          commit(target) {
+            const stored = []
+            for (let index = 0; index < names.length; index++) {
+              const name = names[index]
+              // A with/catch target can receive a var initializer while the
+              // declaration still establishes its own previously absent name.
+              if (!mapHas(pending, name) && (mapGet(kinds, target) !== 'var' || !needsDeclaration(name))) continue
+              if (storeValue(name, mapGet(pending, name), { readOnly: setHas(protectedNames, name), declaration: true,
+                nativeKind: mapGet(kinds, target) ?? 'let' }) === undefined) continue
+              appendArray(stored, name)
+            }
+            mapClear(pending)
+            published = true
+            for (let index = 0; index < stored.length; index++) {
+              const name = stored[index]
+              publish(name, () => read(name), value => write(name, value))
+              changed(name, 'local')
+            }
+            commit(target)
+          },
+        }
+      },
+    }
+    dynamicRuntime.setRootEnvironment(() => result.dynamic({ realm: true }))
+    // Only new-generation environments select intrinsic interfaces. Native
+    // global/prototype properties and saved legacy identities remain intact.
+    if (dynamicIntrinsics !== undefined) {
+      dynamicRuntime.installIntrinsics()
+      moduleRuntime.installIntrinsics()
+    }
+    return result
+  }
+  return {
+    begin,
+    read,
+    legacyReference(name, writable) {
+      const kind = mapGet(entries, name)?.nativeKind ?? 'let'
+      return { kind: includes(['var', 'eval-var', 'hoisted'], kind) ? 'var' : kind,
+        get: () => read(name),
+        typeof: () => mapGet(entries, name)?.deleted === true ? typeofAmbient(name) : typeof read(name),
+        set(value) {
+          if (!writable) throw new errors.TypeError('Assignment to constant variable.')
+          write(name, value)
+        },
+        declare() { write(name, undefined, { declaration: true }) },
+        delete() {
+          const entry = mapGet(entries, name)
+          if (entry.nativeKind !== 'eval-var') return false
+          mapSet(entries, name, { ...entry, deleted: true })
+          return true
+        },
+      }
+    },
+    publishLegacy(name, writable, binding, object = false) {
+      mapSet(entries, name, binding === undefined
+        ? { source: 'local', readOnly: !writable, legacyWritable: writable, object, read: () => readAmbient(name) }
+        : { source: 'import', read: () => {
+          const namespace = readAmbient(binding.namespace)
+          return binding.imported === undefined ? namespace : namespace[binding.imported]
+        } })
+      publish(name, () => read(name), value => write(name, value))
+      changed(name, binding === undefined ? 'local' : 'import')
+    },
+    localValue(name) {
+      const entry = mapGet(entries, name)
+      return entry?.source === 'local' && entry.object !== true && entry.read === undefined ? { value: entry.value } : undefined
+    },
+    has: name => mapHas(entries, name) && mapGet(entries, name).object !== true && mapGet(entries, name).deleted !== true,
+    facts() {
+      const facts = []
+      mapForEach(entries, (entry, name) => appendArray(facts, { name,
+        source: entry.deleted === true || entry.object === true && !hasAmbient(name) ? 'absent' : entry.source,
+        ...(entry.writeTarget === undefined ? {} : { write: entry.writeTarget }) }))
+      return facts
+    },
+  }
+}

package/internal/typert-codec-compat.js

@@ -0,0 +1,28 @@
+/**
+ * Own the strict codec shape PTC Plus publishes into DSH's TYPERT registry.
+ *
+ * A strict codec decodes one wire member. DSH changed where the host reads that
+ * decoder: the preceding generation keeps it on `codec.schema` and evaluates
+ * `codec.schema.parse(value)`, while the current generation keeps a `create()`
+ * factory and evaluates `codec.create().parse(value)`. Each generation validates
+ * the member it owns and ignores the other, so every codec here publishes both
+ * and serves whichever shape the installed host implements — no version gate, no
+ * second registration path, and one decoder for both.
+ *
+ * The decoder is the maintained schema runtime, presented as the `parse` member
+ * both generations evaluate. Business payload validation stays with the owner of
+ * each RPC contract.
+ *
+ * @param {object} options - `typeSymbol` names the wire type; `schema` is the
+ *   maintained schema the decoder evaluates.
+ * @returns {object} a strict codec accepted by either generation.
+ */
+export function strictCodec({ typeSymbol, schema }) {
+  const decoder = { parse: schema }
+  return {
+    mode: 'strict',
+    typeSymbol,
+    schema: decoder,
+    create: () => decoder,
+  }
+}

package/internal/typescript-transform.js

@@ -0,0 +1,31 @@
+import loadAmaro from './compiler-amaro.cjs'
+
+export { LEGACY_USER_BINDING_TRANSFORM, PREVIOUS_USER_BINDING_TRANSFORM, USER_BINDING_TRANSFORM,
+  PROTECTED_MODULE_TRANSFORM, isStatefulUserBindingTransform,
+  historicalModuleTransformForLanguage, moduleTransformForLanguage, moduleTransformMatchesLanguage,
+  normalizeModuleTransform, supportedUserBindingTransform } from './module-transform-contract.js'
+
+/** Keep binding-module lowering independent of the Host's experimental transform API. */
+export function transformTypeScriptModule(source) {
+  return transformTypeScriptSource(source).code
+}
+
+export function transformTypeScriptSource(source, options = {}) {
+  try {
+    return loadAmaro().transformSync(source, { mode: 'transform', sourceMap: false, ...options })
+  } catch (error) {
+    if (error instanceof Error) throw error
+    throw new SyntaxError(error.message, { cause: error })
+  }
+}
+
+let nativeUsingSupport
+
+/** Node 22.19 does not parse explicit resource declarations by default. Keep
+ * one compiler-owned fallback so every source entry gets the same disposal
+ * semantics until the host parser proves native support. */
+export function supportsNativeUsing() {
+  if (nativeUsingSupport !== undefined) return nativeUsingSupport
+  try { Function('using __ptc_resource = null')(); nativeUsingSupport = true } catch { nativeUsingSupport = false }
+  return nativeUsingSupport
+}

package/internal/user-binding-authoring.js

@@ -0,0 +1,70 @@
+import { deepFreeze } from './record-utils.js'
+
+export const BINDING_SUBMISSION = deepFreeze({
+  name: 'submitBindingDraft',
+  description: 'Submit a Global User Binding draft for user review during /binding. Call inside run_code with the supplied requestId. Validates source and accepts one draft per request; does not save, enable or run it.',
+  parameters: {
+    type: 'object', additionalProperties: false, required: ['requestId', 'entry'],
+    properties: {
+      requestId: { type: 'string', description: 'Copy from the active /binding request.' },
+      entry: {
+        type: 'object', additionalProperties: false,
+        required: ['id', 'name', 'scope', 'purpose', 'source'],
+        properties: {
+          id: { type: 'string', description: 'Stable storage ID: 1-64 ASCII letters, digits, dots, underscores or hyphens; starts with a letter or digit.' },
+          name: { type: 'string', description: 'namespace: JavaScript identifier used directly as the call name; top-level: display label.' },
+          scope: { type: 'string', enum: ['namespace', 'top-level'] },
+          symbols: { type: 'array', items: { type: 'string' }, description: 'Named value exports to expose; omit to select all. Names must exist in source.' },
+          purpose: { type: 'string', description: 'One factual line explaining the API.' },
+          modelContext: {
+            type: 'object', additionalProperties: false,
+            description: 'Model documentation when enabled: includeDeclaration selects the source-derived interface (default true); instructions supplies a separate usage prompt (default empty, at most 4096 characters).',
+            properties: {
+              includeDeclaration: { type: 'boolean', description: 'Include the source-derived interface (default true), independently of instructions.' },
+              instructions: { type: 'string', maxLength: 4096, description: 'Usage prompt for the model: when to call this API and any constraints absent from its types. Empty omits the prompt.' },
+            },
+          },
+          source: { type: 'string', description: 'Complete TypeScript module with named value exports, explicit useful types, no default exports or re-exports.' },
+        },
+      },
+    },
+  },
+  returns: {
+    type: 'object', additionalProperties: false, required: ['accepted', 'id', 'requestId'],
+    properties: { accepted: { const: true }, id: { type: 'string' }, requestId: { type: 'string' } },
+  },
+  effect: 'ptc-state', authority: 'ptc-plus-program-binding', completeness: 'complete', replay: 'recorded-value',
+})
+
+export const BINDING_AUTHORING_SDK = `
+During /binding, submit a draft for user review from run_code using the supplied requestId. Submission does not save, enable or execute it.
+\`\`\`ts
+declare namespace code {
+  function submitBindingDraft(args: {
+    requestId: string;
+    entry: { id: string; name: string; scope: "namespace" | "top-level"; symbols?: string[]; purpose: string; source: string; modelContext?: { includeDeclaration?: boolean; instructions?: string } };
+  }): Promise<{ accepted: true; id: string; requestId: string }>;
+}
+\`\`\``
+
+export function bindingAuthoringInstructions(requestId, cwd) {
+  return `Create exactly one Global User Binding candidate for the user's requirement.
+
+Develop and check the helper in small run_code cells before submission. Start with a small executable check of the core behavior, then extend it using in-memory inputs and assertions for normal cases, edge cases and failures. Use node:assert/strict for comparisons. Keep the candidate and reusable test inputs in REPL variables; correct them from observed results and recheck changed behavior. For bulk tests, print totals and a few representative failures, keeping successful cases out of the output.
+
+Tests must not write or delete files, change external services, or call effectful tools. For filesystem or network helpers, use in-memory substitutes and check argument forwarding and error propagation. Check imports and initializers before executing them; review unknown effects without running them. A substitute verifies only the behavior its assertions cover; real integration remains untested.
+
+Review the final source, selected exports, types and usage prompt against the requirement and tested implementation. Keep test scaffolding out of the submitted module. In the answer, briefly report verified behavior and remaining limits; distinguish test-harness errors from helper errors and cite only behavior supported by the checks.
+
+Submit from run_code with code.submitBindingDraft({ requestId: ${JSON.stringify(requestId)}, entry }). One valid submission completes this request; correct validation errors and retry only rejected submissions. The receipt confirms a disabled draft awaiting the user's save decision. Saving and enabling belong to the user.
+
+Candidate contract:
+${Object.entries(BINDING_SUBMISSION.parameters.properties.entry.properties).map(([name, field]) => `- ${name}: ${field.description ?? field.enum.join(' | ')}`).join('\n')}
+
+Use namespace scope for a compact API: name "textHelpers" with export "trim" is called as textHelpers.trim(...). Top-level scope exposes selected exports directly. Supply complete TypeScript module source with useful types and API comments; the interface is generated from it. Do not supply entry.enabled or entry.declaration. Include modelContext.includeDeclaration and modelContext.instructions; leave instructions empty when the interface is sufficient, otherwise add only usage information missing from it. On edit, preserve the entry ID and existing prompt preferences unless the requirement changes them.
+
+Relative imports in saved modules resolve from ${JSON.stringify(cwd)}, the binding storage directory, rather than the session cwd used by ordinary REPL cells. Prefer Node built-ins when sufficient; inspect dependencies only as needed. The selected entry is supplied for edits. Do not read or modify binding storage or unrelated entries, or scan the host installation to discover this API.
+
+Submission example:
+await code.submitBindingDraft({ requestId: ${JSON.stringify(requestId)}, entry: { id: "text-helpers", name: "textHelpers", scope: "namespace", purpose: "Trim surrounding whitespace.", source: "export function trim(value: string): string { return value.trim() }", modelContext: { includeDeclaration: true, instructions: "" } } })`
+}