Binding and capability analysis

oracq.infrastructure.linking

Gap analysis of open oracles, partial binding and QRAM captured resource promotion.

class oracq.infrastructure.linking.OracleRequirement(name, paradigm, path, registers, attributes)

Bases: object

Describe an unimplemented open oracle declaration and its call sites.

Variables:

• name (str) – module name of the open declaration, i.e. the slot name used at binding time.

• paradigm (str) – oracle_paradigm paradigm designated by the declaration.

• path (tuple[str, ...]) – sequence of module names along the shortest call path from the entry module to the declaration.

• registers (tuple) – formal register signature tuple of the declaration.

• attributes (tuple) – attribute entry tuple of the declaration, each a key-value pair.

name

paradigm

path

registers

attributes

class oracq.infrastructure.linking.Binding(operation, resources=None)

Bases: object

Bind an open declaration slot to an implementing operation, optionally carrying a QRAM resource mapping.

Variables:

• operation (oracq.infrastructure.builder.Operation) – Operation providing the implementation; its module name must differ from the declaration slot name.

• resources (dict[str, str] | None) – mapping from the implementation’s formal resource parameters to entry logical resource names; resources not explicitly covered are auto-captured as slot name__resource name and promoted to entry resources.

operation

resources = None

class oracq.infrastructure.linking.BindingIssue(code, path, expected, actual, message)

Bases: object

Structured reason for a binding failure; makes no claim of proving the oracle’s mathematical semantics.

code

path

expected

actual

message

exception oracq.infrastructure.linking.BindingError(issues)

Bases: ValidationError

Binding diagnostic that remains compatible with ValidationError.

class oracq.infrastructure.linking.BindingReport(source_digest, result_digest, bindings, resource_mappings, remaining, resources, issues=())

Bases: object

Binding manifest, program fingerprints and remaining dependencies; stores only exchangeable data.

source_digest

result_digest

bindings

resource_mappings

remaining

resources

issues = ()

property ok

Whether this binding passed the structural checks; does not require every slot to be closed.

to_dict()

Emit a JSON-friendly report, saved independently of the executable RIR.

class oracq.infrastructure.linking.BindingResult(program, report)

Bases: object

Program and report of one binding, avoiding a second linking pass after checking.

program

report

require()

Obtain the program when binding succeeded, otherwise raise the structured issues.

oracq.infrastructure.linking.bind_with_report(program, bindings)

Perform one pure-functional binding, returning a directly usable program plus a traceable report.

Invalid input programs are still rejected by validate; binding errors of candidate implementations are recorded in the report. Data contents are not part of the RIR fingerprint, and run records must identify the QRAM data snapshot separately.

oracq.infrastructure.linking.calls(nodes)

Yield all module call nodes in an instruction body, including nested structure blocks, in order of appearance.

Parameters:

nodes – instruction body to scan; None or an empty tuple is treated as no content.

Returns:

Call nodes lazily yielded in order of appearance, including inside nested blocks.

Return type:

Iterator[Call]

oracq.infrastructure.linking.stores(nodes)

List all Store side effects in an instruction body, including nested structure blocks.

Parameters:

nodes – instruction body to scan; None or an empty tuple is treated as no content.

Returns:

Store nodes lazily yielded in order of appearance, including inside nested blocks.

Return type:

Iterator[Store]

oracq.infrastructure.linking.uses_store(program)

Whether a QRAM random write exists in any entry-reachable module.

Parameters:

program – RIR program to check, traversed from the entry along the call graph.

Returns:

True when any entry-reachable module body contains a Store node.

Return type:

bool

oracq.infrastructure.linking.unresolved(program)

List structurally reachable unimplemented declarations from the entry, with the first shortest call path for each.

Parameters:

program – RIR program to analyze; structural validation runs first.

Returns:

list of open declaration requirements sorted by declaration name, each recording the first shortest call path from the entry.

Return type:

tuple[OracleRequirement, …]

oracq.infrastructure.linking.capability_table(program)

Derive the transformation capabilities of all modules in one traversal.

Parameters:

program – RIR program to analyze, traversing all its modules.

Returns:

mapping from module names to capability dicts; modules containing Store side effects have all capabilities False.

Return type:

dict[str, dict[str, bool]]

oracq.infrastructure.linking.capabilities(program, key=None)

Return the transformation capability dict of a given module, the entry by default.

Capability values are derived by conservatively conjoining the module declaration with the capabilities of called modules; see capability_table.

Parameters:

• program – Program to analyze.

• key – target module name; the entry module is used when omitted.

Returns:

boolean dict keyed by supports_adjoint and supports_controlled.

Return type:

dict

oracq.infrastructure.linking.bind(program, bindings)

Bind declared slots; newly added QRAM resources are promoted explicitly along the module graph, and other slots may stay open.

Parameters:

• program – Program or Operation containing open declaration slots.

• bindings – mapping from declaration slot names to Binding or a bare Operation.

Returns:

revalidated program after binding and promoting captured resources; untouched slots stay open.

Return type:

Program