Universal requirement resolver

How StillMade fills Block inputs from upstream outputs, project context and user answers.

Universal requirement resolver

The public SDK exports createUniversalResolver(), the same implementation used by the Project Type composer, runtime input resolution and native explanations. The older block-platform/universal-resolver.js import reexports this engine.

Interactive JavaScript user requests

The Node SDK host may explicitly provide runPackageAsync(..., {requestFromUser}). An isolated Block can return StillMade.requestFromUser('name') for a missing, optional, non-context input whose contract allows user answers. Check StillMade.resolveRequirement('name').resolved first. The SDK resumes the code from its beginning with the validated answer in input.name; this is a cooperative return, not a Promise or an in-sandbox host callback. Avoid emitting outputs before returning the request. Other inputs remain unchanged.

Both worker boundaries validate the exact declared question and answer. Questions cannot collect credentials, overwrite existing values, widen permissions, or call providers. At most 20 questions are allowed. The Node worker pauses its cumulative five-second execution allowance while waiting, with a five-minute answer deadline; the guest's cumulative CPU and memory limits remain in force. Cancellation ends the run. Successful results include userAnswers for the host to persist alongside execution provenance. Hosts without the callback fail closed.

The application browser runner enables this bridge for individual non-batch JavaScript Step runs. It rechecks project identity, edit access, source admission, and the captured input snapshot around each question. Reviewed answers become semantic user values and contribute to the accepted run's input digest and output dependencies. Other browser callers must explicitly supply both a question handler and a current-project guard; otherwise interactive requests remain unavailable. Browser execution pauses its cumulative worker allowance during a bounded question wait, without expanding the guest CPU allowance. Batch questions, automatic in-run Chat, and shared credit accounting remain unfinished.

Interactive connected local runs now also forward user requests for JavaScript Steps with stop-on-error, bounded retry, or approval-before-retry policies, including connected media batches. The workflow runner independently validates each question, captures the reviewed answer, and requires the executor to return exactly those answers. The accepted input digest includes them, and retained results restore/revalidate optional answers without opening dialogs or rerunning completed Steps. Connected job deadlines still apply; fallback/recovery policies and unattended runs do not enable these questions. Retries receive previously reviewed answers as existing inputs instead of asking again. Each attempt may return only answers newly reviewed during that attempt; the workflow retains the aggregate and binds it to the successful result. Late replies from an ended attempt cannot change the retained answer set.

Connected batch questions name the current source asset and version. Answers are scoped to that target's run and do not silently carry into the next target. Resume validation binds them to the full source snapshot as well as the package, workflow, and effective inputs. Standalone single-Step batch previews also enable questions. Each preview keeps its own reviewed answers and input fingerprint. Using a result rechecks source, settings and answers, then registers the selected answers and outputs as the adopted single-Step result. Previews alone do not overwrite saved answers or advance saved Block memory.

Structured collections use a one-element schema array, such as schema: [{word: 'string', start: 'number', end: 'number'}] on an object[] contract. That schema describes every item, not a tuple or a fixed-length value. It also works inside object fields. Validation and connection compatibility check each item's required fields; plain object[] cannot promise those fields. The input dialog collects structured list items using their declared fields.

Built-in connection adapters also support ordered lists when both endpoints are scalar types with list variants. Each list adapter pins the scalar adapter version, converts at most 100 items, checks each item, and requires all context grants before conversion. A failed item rejects the entire conversion; no partial list is emitted. List-to-scalar flattening, implicit Block fan-out, and nested lists are not inferred. For example, text[] with meaning narration_script can supply script[] with the same meaning through list-text-to-script-v1 version 1. These are local data conversions, not separately billed provider calls or general workflow batches.

import {createUniversalResolver,input} from './packages/block-sdk/index.js';

const requirement=input({
  key:'company',type:'object',semantic:'company_profile',required:true,
  description:'Company information',schema:{name:'string'},sources:['project']
});
const resolver=createUniversalResolver();
const options={values:[{
  id:'company-profile',revision:1,type:'object',semantic:'company_profile',
  value:{name:'Morning Bakery'},source:{kind:'project'},permissions:[]
}]};
const explanation=resolver.inspect(requirement,options);
const resolved=await resolver.resolve(requirement,options);

inspect and explain return the selected source, reason and candidates. listCandidates returns priority-ordered alternatives. resolve checks actual values and returns source/dependency metadata. A required unresolved input stays unresolved; a pending callback can return one clarification question.

Pass an explicit semantic registry and versioned adapter registry when needed. The host may supply canDerive, requestFromChat and requestFromUser callbacks. No callback is provided automatically. Permission and freshness filtering applies to context passed to those callbacks; source/schema validation still applies to their results. Use stable record IDs and revisions for executable values. Plan mode can inspect declarations that do not yet contain a value; resolve always requires materialized values or an answer callback.

Callbacks receive isolated copies. Final resolution rechecks dependency freshness after waiting for an answer and rejects expired sources or missing revisions. The host must still detect edits to the underlying project while resolving; a copied context snapshot does not subscribe to storage changes.

This is a trusted-host/authoring library, not a new guest API or permission grant. It does not fetch project data, mutate projects, run Blocks, approve purchases, authorize credentials, or enforce a provider spending budget. Hosts must retain their existing scoped storage, sandbox, approval, cancellation and shared-budget boundaries around integrations. Do not register arbitrary creator code as a host callback. Download assembly includes this module, but generated download artifacts must be rebuilt separately.

Custom meanings and connection checks

Pass the same explicit semantics registry to the universal resolver and to compatible, connectionCompatibility, validateConnectionAdapter and adaptConnectionValue. The optional argument is {semantics}; adapter calls retain their existing permission, context and exact-version pin options. Inheritance widens only meaning compatibility, never physical types, schemas, permissions or adapter versions. Without a registry, only the standard semantic relationships apply. No process-global registry is mutated by these calls.

The application composition helpers accept the same scoped registry for audits, automatic connection selection, explicit source selection and recommendation checks. Store reusable definitions in manifest.semantics:

semantics: [{
  name: 'creator.example.spoken_copy',
  description: 'Words to read aloud.',
  parents: ['narration_script']
}]

Each Block may declare up to 64 namespaced meanings, eight parents per meaning and 500 description characters. Definitions cannot override unnamespaced standard meanings. Duplicate names within a Block, cycles, and conflicting parent sets across selected versions are rejected. Matching definitions may be shared. The source and release digest includes these declarations; changing a published definition requires a new release, not editing an immutable version.

semanticRegistryForManifests(manifests) reconstructs a scoped registry from saved contracts. Composer audits and local workflow execution load these package definitions automatically. Connected execution captures their exact snapshot in the execution-plan digest. Explicit injected registries are still ephemeral; only package declarations survive save/reopen. Guest access to arbitrary project context, generated adapter execution and automatic metered Chat derivation are separate integrations, not permissions granted by declaring a meaning.

Direct structured answers

The application's reviewed-answer dialogs collect required schema fields with typed controls, leaving optional fields unasked and preserving existing optional answers during edits. Unstructured objects offer named details with text, number, yes/no, nested-detail, list and empty-value choices. Object and JSON lists support adding, editing and removing items without requiring JSON syntax. Primitive schemas on JSON inputs choose the corresponding typed question.

These dialogs serve the existing lazy user resolver, shared-default editor and connected preview samples. They capture the contract and previous answer before waiting, validate the final value and return nothing on cancellation. Collection is bounded to 20 recursive questions, 60 menu choices, 20 detailed list items or object fields, and the existing 8,000-character scalar/simple-list limits. Larger answers still need the appropriate settings editor. Source permissions and credential restrictions remain enforced by the calling resolver; these controls do not create new runtime authority or automatically invoke Chat.

Single-Step and connected-run missing-answer collection use the same universal resolver for allowed defaults and user callbacks. A permitted default is selected before asking; it is not recorded as a user answer. Retained reviewed answers remain explicit replay inputs. Contract, supplied-input and retained-answer snapshots are captured before waiting, and callbacks cannot claim dependencies on unavailable context. Existing host scope checks still reject edits to the real project during collection. This does not enable automatic paid Chat calls.

Versioned document conversions

The shared connection registry includes csv-file-to-table@1, text-to-script@1 and script-to-text@1. Visual/native composition, explicit connection pins and semantic context resolution use the same descriptors.

CSV files must be single inline .csv files declared with the csv meaning; the result has the table meaning and {columns, rows} schema. Archives, remote media and malformed CSV are rejected. The existing CSV limits and string-preserving parser apply; cell contents are never executed.

Script conversions preserve semantic compatibility and exact words. Wrapping adds only {schemaVersion: 1, text}; unwrapping requires readable text and does not carry other script metadata into the text output. Neither conversion turns research notes into narration or invents additional required fields. Candidate checks validate actual values when present. Version pins, source policy, inherited permissions and provenance remain enforced. These are deterministic built-ins, not arbitrary multi-hop or creator-code adapters.

Conditional SDK Steps

Existing Step conditions support greater-than, at-least, less-than and at-most in addition to presence and equality comparisons. Numeric thresholds must be finite numbers; missing values, strings and booleans do not satisfy a numeric comparison. Safe field paths and existing default handling still apply. The builder and native set_condition control share setProjectTypeCondition; use null to remove a condition. Native Step inspection includes its condition.

These conditions retain the existing false-case behavior: pass the primary input unchanged to a single compatible output. They do not create general branches, invent outputs, enable hosted-workspace conditions or grant execution approval.

Reviewed Chat suggestions share canSuggestRequirement eligibility across the application and server. Supported information includes scalar text/numbers/ booleans, script documents, objects, JSON and their supported lists. Host-bound context, credential-sensitive inputs and inputs excluding Chat remain ineligible. The server captures the notes and requirement before waiting and validates the returned value before issuing matching provenance. This remains a reviewed suggestion, not automatic workflow dispatch or a budget authorization.

Saved-project source updates

Project Type connections use the Block's declared input and output contracts, including Blocks a creator adds later. A reviewed source change updates that project's binding and marks affected results stale; it does not run a Block. An explicit affected-Step update can then reuse a current saved upstream value. The runner pins that value before dispatch and records its producer placement, output port and run ID in the receiving run's captured input identities. The pin is checked again during execution, so a changed upstream result requires a fresh review. Text and structured input contents are not copied into this identity record; inspect the authorized value separately when needed.

Recommendation execution evidence

The hosted completion signal uses server-owned, terminal production capability runs for an exact public release digest over 30 days. It excludes creator self-use, suspended accounts, revoked releases, previews, cancellation and unresolved remote work. At least five terminal runs from three users are needed; each user contributes at most 20 recent runs per release. A smoothed completion adjustment between minus two and plus two points supplements, but cannot replace, capability coverage and connection validation. Creator-supplied quality numbers are not used.

This signal measures terminal execution completion, not generated-content quality, local execution reliability or resistance to coordinated account abuse. Missing evidence contributes no adjustment and does not mean failure. A measured completion rate below one half lowers ranking rather than earning a bonus; a rate of one half is neutral. The response reports signal availability and the number of measured releases. Cost, latency and creator reputation remain unmeasured ranking signals.

Visual recommendation Details explains these limits and measured-Block coverage. Native recommendation inspection includes the same signal availability and warnings, alongside per-proposal score explanations.

Guest workspace patch proposals

JavaScript Blocks can call StillMade.patchProject(outputKey, {field, title, after}) to emit a reviewed workspace-edit proposal. Declare a workspace-edit output, a matching context input, and both context.<field>.read and workspace.<field>.propose permissions. The helper obtains before from the original host-supplied context snapshot, not the guest's mutable input. It returns no value and uses the ordinary output collector: emit each output once and do not also return an output object.

This method does not apply an edit, save a project, grant permissions or call the host from the sandbox. Final outputs pass the existing workspace-edit and permission validators; the host's review and stale-document checks still decide whether a proposal can be applied. Only existing workspace-edit fields are supported, not arbitrary project fields or credentials. Guest Chat/user request bridges and broader project mutation remain separate unfinished integrations.

Bounded adapter paths

Creator-owned conversion Blocks

When two admitted Blocks declare incompatible inputs and outputs, the Project Type builder can search saved Blocks for a real intermediate Step. Find converter Blocks inspects each candidate's versioned ports and source policy; it does not run the candidate or infer that its result is correct. Choosing one embeds the exact package version and creates two ordinary typed connections. The connected runner executes the intermediate Block through its declared runtime and validates its output before the receiver runs. Saved-project Flow can search converter packages already embedded in that Project Type and review the migration before adding an instance. This route preserves each Block's own implementation and does not install a creator's transform in the trusted host.

The on-demand search discovers paths of up to three intermediate Blocks with bounded exploration. Longer routes can still be composed as ordinary Steps. New Marketplace package search from an existing project and full native/hosted acceptance are still required for general interoperability. A source preview in the search is never presented as a converter's unrun output.

Trusted resolver callers can opt into maxAdapterHops: 2 or 3. The default remains one for compatibility with existing saved connection pins. Registries expose findPaths(source, requirement, options) and applyPath([{id, version}, ...], source, requirement, options). Search uses contract compatibility without executing transforms, examines at most 512 edges and returns at most 16 paths. inspect reports searchTruncated when those limits prevent an exhaustive search.

Execution preflights the complete chain's permissions and contracts, validates each intermediate result, preserves the original source's freshness and returns provenance containing every conversion pin plus the original source revision. These are trusted registered adapters, not creator-code execution authority. Saving and executing chain pins in the visual/native application is not yet integrated; existing connection paths remain unchanged.