Previz/Developers/Developer concepts

    Projects and engine policy

    by the PREVIZ team

    Why every PREVIZ call names a project, and how that project's engine policy decides which engines may touch the work before a credit moves.

    The project is the unit

    Nearly every tool takes a projectId. The project is where the work lands (its storage, its Infinitum board, its continuity banks), whose policy applies, and whose activity records it. list_projects names the projects the key can reach, newest first; start there, and keep the id.

    A tool that makes something answers with a where block: the project, the room, whether the result is on the board, the PREVIZ address that opens the room on it, and the file itself. Hand the openUrl to your person; it is how a render made by a program is found by a human.

    Engine policy travels with the project

    A project can carry an engine routing policy: a client contract that excludes engines by operator or jurisdiction, for example. Calls through the door run through the same gated functions the studio runs, so the policy applies to an agent exactly as it applies to a person. A step the policy refuses is refused before a credit moves, with the reason.

    plan_quote runs the policy as a dry run for every step of a plan, so an agent learns which steps a project would refuse before it starts, not halfway through. The answer names whether the project is restricted and the policy's label.

    Rules for agents: what an organisation lets a tool do

    An organisation's owner or admin can set a rule per tool, in PREVIZ, for every member's keys and connected apps and for anyone's call on the organisation's projects: never (the call is refused with GOVERNANCE_DENIED before its arguments are read), ask a person first, or run. A person can set rules for their own credentials in the same three words. The strictest rule always applies, so a person's own rule can only add to their organisation's and never loosen it. No tool sets a rule; get_governance reads every rule that binds the credential it is called with.

    Ask first applies where a price is pressed: every paid tool, a chain as a whole, a re-shoot of stale work, and a production's priced decision. A quote is still answered, and says the run will wait. The run then answers input_required with the page a signed-in person approves on, the price on the button, and nothing is charged until they do; call the tool again with the approvalId once they have. A rule that asks about every tool leaves free tools alone, and a credential a press cannot be offered to is refused with GOVERNANCE_NEEDS_PERSON.

    The rules are part of the fingerprint every quote is bound to. A rule set or changed after a quote makes that quote stale (QUOTE_STALE), so an agent never runs on yesterday's permission; ask for a new quote. Five tools are never governed, so an agent can always learn where it stands and stop: get_account, get_governance, freeze, cancel_job and stop.

    An audit trail that shows its own tampering

    Every call through the door is one line in an audit log, and every line is sealed into a single chain: a seal's hash is computed over the seal before it and the line's own fields. A line changed afterwards, removed from the middle or inserted later breaks the chain at that point. get_audit_log answers each call's seal (hash, prevHash) about a minute after the call, so a program can check for itself that no two of the lines it holds claim the same place and that neighbouring lines link. The chain's length is not shown: it would be a count of every customer's calls.

    At the end of each day PREVIZ signs where the chain stood (get_audit_log answers the last signed head, the exact text that was signed, and where the public key is published). Keep a copy of a signed head and nobody, PREVIZ included, can rewrite the log before it without the copy showing it.

    Capabilities, not vendors

    Answers name the capability that made a result (a frame, a take, a mesh, a depth map), never an engine vendor's model id. Which engine served a capability is a routing decision PREVIZ makes under the project's policy and may change as engines improve; a program that keyed on a vendor's id would break the day the route moved. provenance_report gives the per-asset chain of custody: the capability, the credits spent, the render time, the ancestry and the locks that rode.

    The same rules as a button

    Nothing reached through the door bypasses the studio. Every spending tool runs through the same metered function the corresponding button in the studio runs, with the caller's identity carried server-side, so gates, billing, refunds and provenance are identical to a person pressing it. There is no cheaper, faster or less checked path for programs, and there is no second price list.

    The tools this is about

    list_projects
    List projects
    plan_quote
    Price a plan
    provenance_report
    Read provenance
    get_governance
    Read the rules for agents
    get_audit_log
    Read the audit log

    Other concepts